文档工具选型踩坑半年后，我重新理解了什么叫“写代码不如写文档”
裸辞Gap半年回来找工作，说实话，心态有点崩。前大厂待久了，以为简历上写着“精通分布式系统”、“SpringBoot微服务架构经验”就能横着走，结果面试官问：“你项目文档怎么管理的？”——当场愣住。
不是没写过文档，但大多是临时起意、零散在Confluence里，或者藏在README.md角落，连自己三个月后都看不懂。更惨的是，有次面试时被要求现场讲一个模块的设计思路，翻了半天本地笔记，发现关键逻辑全靠脑补，文档里只有一句“这里有个bug，后面再修”。
痛定思痛，这半年刷题之余，我花了不少时间重新梳理文档工具链。尤其是作为后端开发者，天天和SpringBoot打交道，文档不仅是给别人看的，更是给自己留条活路。今天就聊聊我在文档实践中的血泪教训和一些小确幸。
为什么后端工程师也得操心文档？
很多人觉得文档是前端或产品经理的事，后端只要把API跑通就行。但现实很骨感：去年双11前夕，我们组上线一个新订单服务，我负责核心状态机模块。结果上线第二天，测试同学拿着Postman跑不通，问我：“这个状态流转的触发条件到底是什么？” 我翻了翻代码注释，只有一行：
// 状态变更逻辑，别乱改
运维大哥更直接：“你们这服务挂了，日志看不懂，文档在哪？”
那一刻我真想原地辞职。
其实，文档的本质是降低沟通熵。尤其在分布式系统里，一个请求可能跨5个服务，每个服务都有自己的状态语义。如果你不写清楚输入输出、边界条件、失败重试策略，队友（包括未来的你自己）就得靠grep + git blame + 玄学推理来还原上下文——效率低不说，还容易出事故。
我试过的几种文档方案
1. 手搓Markdown + Git（最原始但自由）
Gap期间我一度回归极简主义：所有文档扔进项目根目录的docs/，用Vim写，Git提交。优点是版本可控、无需额外工具；缺点也很致命——没人会主动去看。
比如我给一个内部消息队列中间件写了20页设计文档，结果同事反馈：“链接在哪？怎么搜关键词？能导出PDF吗？” 更尴尬的是，文档和代码不同步。有一次我重构了重试机制，但忘了更新文档，导致下游团队按旧逻辑调用，半夜被PagerDuty叫醒。
2. Swagger + SpringDoc（API文档自动化）
回到求职状态后，我重新拾起了SpringBoot生态里的文档利器。现在基本标配是：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.3.0</version>
</dependency>
加上几行配置，启动应用后访问/swagger-ui.html，API文档自动生成。配合@Operation、@Schema等注解，连请求示例都能生成。
@Operation(summary = "创建订单", description = "幂等接口，重复调用返回相同结果")
@PostMapping("/orders")
public ResponseEntity<OrderDTO> createOrder(@Valid @RequestBody CreateOrderRequest req) {
// ...
}
这玩意儿对简历上的“工程规范”加分不少。面试时展示一下自动生成的交互式文档，HR都能看懂。
但问题在于：Swagger只解决API层，不解决架构设计、部署流程、故障预案等高阶文档。它像一把锋利的手术刀，但你不能拿它盖房子。
3. Docusaurus + GitHub Pages（静态站点方案）
为了搞定非API类文档，我尝试了Meta开源的Docusaurus。用Markdown写，一键构建静态站，部署到GitHub Pages免费又快。支持搜索、多版本、侧边栏导航，甚至还能嵌入Live Code Demo。
我的个人技术博客现在就用它搭的。对于开源项目或内部知识库，这套组合拳很香。但问题是：太重了。每个项目单独维护一套文档站点？运维成本太高。而且和CI/CD流程割裂，经常出现“代码更新了，文档没构建”。
最终方案：轻量、集成、自动化
经过几轮折腾，我现在采用一种“分层+自动化”的策略：
| 文档类型 | 工具 | 更新频率 | 负责人 |
|---|---|---|---|
| API接口文档 | SpringDoc (OpenAPI) | 实时同步 | 开发者 |
| 模块设计文档 | Markdown + Git | 迭代更新 | 模块Owner |
| 部署/运维手册 | Confluence | 发布前更新 | DevOps |
| 故障复盘报告 | Notion | 事后48h内 | On-Call工程师 |
关键点在于：让文档成为开发流程的一部分，而不是额外负担。
比如在我们的CI流水线里加了一条规则：如果PR修改了Controller层，必须包含对应的OpenAPI注解更新，否则CI卡住。虽然一开始被同事吐槽“形式主义”，但几次线上问题后，大家反而主动加注释了。
另外，我写了一个小脚本，每天凌晨自动拉取所有服务的OpenAPI spec，合并成一个全局API目录，推送到内部Wiki。这样产品和测试同学再也不用问“哪个服务提供用户信息接口”了。
#!/bin/bash
services=("user-service" "order-service" "payment-service")
for svc in "${services[@]}"; do
curl http://$svc.prod:8080/v3/api-docs > specs/$svc.json
done
node merge-specs.js # 合并为 single.yaml
git add . && git commit -m "Auto-update API catalog" && git push
安全意识：文档也是攻击面
很多人忽略一点：公开的文档可能泄露敏感信息。
有次我差点犯大错：在Swagger里暴露了一个内部调试接口，路径是/admin/internal/debug，里面能直接执行SQL。幸好Code Review时被安全团队揪出来。从此以后，我们强制要求：
- 所有
@Hidden或@ApiIgnore标注内部接口 - 生产环境禁用Swagger UI（通过profile控制）
- OpenAPI spec中过滤掉敏感字段（如密码、密钥）
甚至在简历里写“熟悉API安全规范”时，我都会特意提一句文档脱敏实践——这比单纯说“用过JWT”更有说服力。
给正在跳槽的同行一点建议
如果你也在准备后端岗位的面试，别只盯着LeetCode。花半小时整理一份清晰的项目文档，可能比刷三道Hard题更管用。
我最近一次面试，面试官让我讲一个复杂系统的设计。我没直接讲代码，而是打开提前准备的架构图（用Mermaid画的）+ 关键接口示例 + 故障处理流程。他说：“你是我今天见到第一个带文档来面试的。”
那一刻我知道，Gap半年没白过。
写在最后
文档不是负担，而是工程师的“第二简历”。它记录你的思考深度、协作意识和工程素养。尤其是在大厂，代码可以烂，但文档不能没有——因为没人有时间猜你在想什么。
现在我每天写代码前，先问自己：这段逻辑三个月后我自己能看懂吗？如果不能，那就先写文档。
毕竟，简历上写的“高可用、高并发”谁都会，但能把复杂系统讲清楚的人，永远稀缺。
P.S. 如果你也在用Vim写文档，试试:TOhtml命令，一键生成HTML，比截图优雅多了（笑）。
评论 0