小程序开发文档：别等联调才翻

做小程序这几年，有个现象一直没变：项目刚开始时，没人愿意写文档；等项目做到一半，所有人都在找文档。尤其是多人协作或者中途换人接手的时候，翻聊天记录找接口参数，比写代码还累。这篇就聊聊小程序开发文档这件事，说说哪些文档真值得写、怎么写才不流于形式。

先想清楚：文档是写给谁看的

很多团队一上来就套模板，需求文档、设计文档、测试文档全套齐活，结果写完没人看。我的经验是，先分清读者：

• 给未来的自己看：接口约定、字段含义、特殊业务逻辑。这类文档最值钱，因为记忆是最不靠谱的。
• 给协作的同事看：环境配置、目录结构、提交规范。新人入职第一天能照着跑起来，就算合格。
• 给后端和运营看：页面路径、参数、埋点事件。他们不一定懂前端，描述要尽量直白。

读者不同，写法就不同。给前端看的接口文档可以写字段类型和示例，给运营看的页面文档就写「从哪进、带什么参数、落地到哪」就够了。

接口文档：最该先写的那一份

小程序前端和后端联调，最容易卡在接口上。与其口头约定，不如在动手前把接口文档定下来。哪怕只是几行表格，也比没有强。我习惯用下面的结构描述一个接口：

接口：GET /api/order/detail
说明：查询订单详情
入参：
  orderId  string  必填  订单号
  withLog  boolean 可选  是否返回操作日志，默认 false
出参：
  code     number  0 成功，非 0 失败
  data     object  订单信息
    status   number  1 待支付 2 已支付 3 已发货 4 已完成
    amount   number  金额，单位分
异常：
  401 未登录，前端跳转登录页
  404 订单不存在，提示后返回列表

注意 amount 用分而不是元，这种细节一定要写清楚。我见过因为单位理解不一致，页面上多显示两位小数的线上事故。状态码枚举也建议直接列出来，别让前端去猜 status === 2 到底代表什么。

目录结构和环境说明别省

小程序项目通常不大，但结构一乱，接手的人就要花半天摸清。建议在仓库根目录放一个 README，写清楚这几件事：

• 项目用原生还是框架（比如 uni-app、Taro），版本号是多少
• 开发、测试、生产三套环境的 appid 和请求域名分别是什么
• 云开发项目要写清楚云环境 ID 和数据库集合的用途
• 本地怎么跑起来，需要装什么、执行什么命令

如果是云开发，尤其要把云函数和数据库的关系画清楚。比如哪个集合存用户、哪个存订单、哪个是日志，云函数之间谁调谁。这块不写明白，后面加功能很容易重复造轮子。

页面文档：路径和参数要能对上

小程序的页面跳转靠路径和参数，页面一多，参数名就容易各写各的。建议维护一份页面清单，至少包含：

1. 页面路径，比如 pages/order/detail
2. 进入方式：tabBar、navigateTo、redirectTo、扫码、分享
3. 接收参数及类型
4. 关键埋点事件名

这份文档不用很正式，一个 Markdown 表格就够。它的价值在于，当运营问「这个页面能不能带参数分享」时，你能直接查表回答，而不是去翻代码。

几个容易踩的坑

文档不是写完就完事，它和代码一样需要维护。区别在于，代码不维护会报错，文档不维护只会悄悄骗人。

• 别把文档写成流水账：按模块组织，别按开发时间顺序记。
• 示例比描述重要：一个真实的请求和响应示例，胜过三行文字说明。
• 变更要留痕：接口字段改了，在文档里标注日期和原因，联调时能少吵很多架。
• 别追求大而全：小项目写接口和目录说明就够，硬套重型模板反而没人维护。

写在最后

小程序开发文档这件事，本质上是在给未来的协作省时间。不用一开始就写得完美，但至少把接口、环境、页面参数这三块定下来。等真正联调或者交接的时候，你会感谢当初多花的那个下午。文档写得好不好，标准很简单：换个人照着它，能不能把项目跑起来、把接口调通。能，就够了。