现状：一个 454K 的 .doc#

APP接口说明.doc 躺在仓库根目录。后端改了字段，文档更新靠自觉；前端照着旧文档调，400 错误靠猜。Word 文档三个绝症：版本不可 diff、字段没有类型、变更不通知。

想要的：契约即代码#

• OpenAPI/Swagger：后端注解生成，前端一键导 dio 客户端，字段改了 CI 就红
• yapi/apifox：mock 先行，前端不等后端
• 哪怕是 Markdown 表格 + git 版本，也比二进制 .doc 强：能 diff、能 blame、能 review

现实妥协：先止血#

推不动重构时，三招止血：接口变更群里 @所有人 + 文档版本号（APP接口说明v12.doc）、pretty_dio_logger 全量报文留档、联调问题贴报文不贴截图。YueQi 的 dio 日志和 logger 就是这么用的——文档会过时，报文不会说谎。

接口文档的终极形态是机器可读，在那之前，先让人可 diff。