用 Node.js 与 Express 构建可上线的 REST API

很多 API 在本地开发阶段看起来没有问题，但一旦进入真实环境，就会暴露出认证、校验、错误处理和文档缺失的问题。真正可上线的 API，重点不是“能跑”，而是“能维护、能扩展、能排查”。

1. 先把目录结构和边界划清

建议至少把配置、路由、控制器、服务层、中间件和校验逻辑拆开。这样做的价值不是形式上的分层，而是让业务逻辑不会散落在每个接口文件里，后续测试和重构都更可控。

2. 认证与鉴权尽量前置

接口一多，权限模型就会迅速复杂。把令牌解析、身份校验、角色判断放到中间件层处理，能避免大量重复代码，也方便统一返回错误格式。

3. 错误处理必须集中收口

不要在每个接口里各写一套 try/catch。更合理的方式是定义业务错误类型，再通过统一错误处理中间件输出稳定的状态码和错误消息。这样做对日志检索、监控告警和前端联调都更友好。

4. 输入校验不要依赖“约定”

参数校验应当在进入业务逻辑之前完成，包括 body、query 和 params。不论使用 Zod、Joi 还是其他方案，关键是把校验规则显式化，避免非法数据进入数据库或核心逻辑。

5. 文档与测试是上线前的最低保障

接口文档至少需要说明输入、输出、错误码和鉴权方式。测试不一定一开始就追求很高覆盖率，但登录、权限、关键写操作和异常分支至少要被覆盖。

结语

如果你把目录组织、鉴权、校验、错误处理和文档这几件事从一开始就做好，后续增加业务功能会顺畅很多，API 的维护成本也会低不少。