curl -s localhost:8080/v3/api-docs | jq '.paths["/api/order"].get.parameters[].name' grep -rn 'pageSize\|size' src/main/java/**/OrderQuery.java
联调时前端按文档传 pageSize，后端已经改成 size 三个月，接口返回 400 参数校验失败。文档最后一次更新是 6 月，代码 9 月改的。这类现象通常不是突然出现的，往前翻半天日志能看到苗头。
追下去是这么回事：文档靠手工维护，改代码时没人想起它。接口变更没有强制更新文档的环节。
「文档与代码不同步」确认了原因之后，改动尽量只碰那一处，顺手改的东西后面最容易出问题。同一份配置存在多处的，先确认改的是被加载的那一份。
新版本先放一台机器上跑一天再全量，问题一般在这段时间暴露。备份不是备了就行，恢复一次才算数，很多备份文件打开才发现是空的。
处理上按这个顺序：用注解或 schema 从代码生成文档 不手写；CI 里加一步校验文档和接口定义一致；字段改名保留旧参数一个版本 并在文档标注废弃；联调前用契约测试跑一遍。
确认没问题再收工，文档里的参数名和接口实际接受的一致，契约测试在 CI 里通过。