用Express.js设计REST API：新手也能上手的实战指南

想象你走进一家餐厅。你不会冲进厨房自己炒菜，而是告诉服务员想吃什么，然后等着上菜。这位服务员，就是你的API。

这篇指南要把你从"听说过REST"变成能独立搭建专业级API的开发者。我们以"用户管理"为例，用Express.js写出现代、简洁、能直接用在生产环境的代码。没有废话，直接上手。

API全称Application Programming Interface（应用程序编程接口），本质是一份"契约"——让两个软件互相通信的规则。客户端（React应用、手机App或Postman）发请求，服务器处理后返回响应。就像外卖App：你下单→餐厅做饭→骑手送餐。你不需要知道厨房怎么运作，只要结果。

REST是Representational State Transfer的缩写，2000年由Roy Fielding提出。它不是协议，而是一种架构风格。RESTful API用标准HTTP方法操作资源，核心特点有四个：无状态（每个请求自带全部信息，服务器不记前账）、用HTTP方法当动词、资源用名词做URL、支持缓存和分层架构。REST能赢，就赢在一个"简"字——简单、可扩展、和Web天生一对。

在REST世界里，万物皆资源，通常是名词：用户、文章、商品、订单。集合路由用复数形式：/users代表所有用户，/users/42代表第42号用户。业内惯例是坚持用复数，读起来顺，也是行业标准。

HTTP方法对应日常动作，以用户资源为例。GET是获取数据，安全且幂等——问服务员"菜单有什么"或"我的菜好了吗"，问多少次结果一样。代码实现上，GET /users返回全部用户，GET /users/:id返回单个用户，找不到就抛404。

POST是创建资源，非幂等——点一份牛排和点两份，结果不同。对应代码是POST /users，接收客户端传来的用户数据，新建记录后返回201状态码和创建好的对象。

PUT是完整更新，幂等——把订单从"三分熟牛排"改成"五分熟牛排"，改多少次结果相同。PATCH是局部更新，只改部分字段——比如只把配菜从薯条换成沙拉。DELETE顾名思义，删除资源，也是幂等——删一次和删十次，结果都是没了。

状态码是API的"表情"。200 OK表示成功，201 Created表示创建成功，204 No Content表示删除成功但无返回体。400 Bad Request是客户端传参错误，401 Unauthorized是没登录，403 Forbidden是权限不够，404 Not Found是资源不存在，500 Internal Server Error是服务器内部出错。用好状态码，前端开发者会感谢你。

路由设计要干净。避免/ getUserById这种动作式命名，坚持用/users/:id。嵌套资源控制在两层以内，比如/users/42/posts合理，/users/42/posts/3/comments/5/replies就太深的。版本号放URL开头，如/v1/users，方便未来升级不 breaking 现有客户端。

Express.js的代码结构也有讲究。把路由、控制器、模型分层：routes/放路由定义，controllers/放业务逻辑，models/放数据操作。中间件处理通用任务——验证身份、记录日志、统一错误格式。async/await处理异步，配合try-catch包裹，别让未捕获的Promise rejection 崩溃整个服务。

最后几个实战细节。请求体大小限制要设，防止恶意大文件拖垮服务。CORS配置要精确，开发环境宽松，生产环境白名单。环境变量管理密钥，绝不在代码里硬编码数据库密码。日志用结构化格式（JSON），方便后续分析。

从"听过REST"到"能写生产级API"，差距就在这些细节里。Express.js的极简哲学让你快速起步，但真正的专业度体现在状态码的准确、路由的语义清晰、错误的统一处理。现在打开编辑器，用这些原则重写你上一个项目的API接口——你会惊讶于代码变得多清爽。