https://example.pages.dev/tags/rest-api/REST APIHugoBlox Kit (https://hugoblox.com)zh-HansTue, 10 Dec 2024 00:00:00 +0000https://example.pages.dev/media/icon_hu_da05098ef60dc2e7.pnghttps://example.pages.dev/tags/rest-api/https://example.pages.dev/blog/building-rest-api/Tue, 10 Dec 2024 00:00:00 +0000https://example.pages.dev/blog/building-rest-api/<p>很多 API 在本地开发阶段看起来没有问题，但一旦进入真实环境，就会暴露出认证、校验、错误处理和文档缺失的问题。真正可上线的 API，重点不是“能跑”，而是“能维护、能扩展、能排查”。</p> <h2 id="1-先把目录结构和边界划清">1. 先把目录结构和边界划清</h2> <p>建议至少把配置、路由、控制器、服务层、中间件和校验逻辑拆开。这样做的价值不是形式上的分层，而是让业务逻辑不会散落在每个接口文件里，后续测试和重构都更可控。</p> <h2 id="2-认证与鉴权尽量前置">2. 认证与鉴权尽量前置</h2> <p>接口一多，权限模型就会迅速复杂。把令牌解析、身份校验、角色判断放到中间件层处理，能避免大量重复代码，也方便统一返回错误格式。</p> <h2 id="3-错误处理必须集中收口">3. 错误处理必须集中收口</h2> <p>不要在每个接口里各写一套 <code>try/catch</code>。更合理的方式是定义业务错误类型，再通过统一错误处理中间件输出稳定的状态码和错误消息。这样做对日志检索、监控告警和前端联调都更友好。</p> <h2 id="4-输入校验不要依赖约定">4. 输入校验不要依赖“约定”</h2> <p>参数校验应当在进入业务逻辑之前完成，包括 <code>body</code>、<code>query</code> 和 <code>params</code>。不论使用 Zod、Joi 还是其他方案，关键是把校验规则显式化，避免非法数据进入数据库或核心逻辑。</p> <h2 id="5-文档与测试是上线前的最低保障">5. 文档与测试是上线前的最低保障</h2> <p>接口文档至少需要说明输入、输出、错误码和鉴权方式。测试不一定一开始就追求很高覆盖率，但登录、权限、关键写操作和异常分支至少要被覆盖。</p> <h2 id="结语">结语</h2> <p>如果你把目录组织、鉴权、校验、错误处理和文档这几件事从一开始就做好，后续增加业务功能会顺畅很多，API 的维护成本也会低不少。</p>