遵循RESTful设计规范可提升API可读性与维护性。1. 使用名词命名路由如/users而非/getUsers；2. HTTP方法对应CRUD操作，GET获取、POST创建、PUT更新、DELETE删除；3. 嵌套路由不超过两层，如/users/1/posts；4. 资源名统一用复数形式如/users；5. API版本控制通过/api/v1/users实现；6. 查询参数用于分页、排序、过滤，如?page=2&limit=10；7. 返回标准状态码如200、201、404；8. 统一响应格式包含success、data、message字段；9. 使用Router模块化管理路由，拆分不同资源至独立文件。
在使用 Express 设计 RESTful API 时，遵循清晰的路由规范能提升代码可读性、维护性和团队协作效率。以下是常见的 JavaScript RESTful API 路由设计规范，适用于 Express 框架。
1. 使用资源名词命名路由
RESTful API 的核心是“资源”，因此 URL 应该使用名词表示资源，避免动词。
-
正确示例：
/users,/posts,/comments -
错误示例：
/getUsers,/deletePost
通过 HTTP 方法（GET、POST、PUT、DELETE）来表达操作意图，而不是放在路径中。
2. 合理使用 HTTP 方法对应 CRUD 操作
每个 HTTP 动作对应标准的资源操作方式：
立即学习“Java免费学习笔记（深入）”；
- GET /resources：获取资源列表
- GET /resources/:id：获取单个资源
- POST /resources：创建新资源
- PUT /resources/:id：更新整个资源
- PATCH /resources/:id：部分更新资源
- DELETE /resources/:id：删除资源
3. 路由层级清晰，支持嵌套但不过度
当资源存在从属关系时，可通过嵌套路由表达，但建议不超过两层。
-
获取某用户的所有文章：
GET /users/123/posts -
获取某文章下的评论：
GET /posts/456/comments -
避免深层嵌套：
/users/1/posts/2/comments/3/replies建议扁平化为/replies?commentId=3
4. 使用复数形式命名资源
统一使用复数形式，保持一致性。
Json Schema Toolkit
下载
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
-
推荐：
/users,/products,/orders -
不推荐：
/user,/product
5. 版本控制 API
在 URL 或请求头中加入版本号，便于后续升级兼容。
-
URL 版本：
/api/v1/users -
推荐做法： 将版本作为前缀，使用
app.use('/api/v1/users', userRouter)
6. 过滤、排序、分页使用查询参数
不要将过滤条件放入路径，使用 query 参数实现灵活查询。
-
分页：
GET /users?page=2&limit=10 -
排序：
GET /posts?sort=-createdAt（- 表示降序） -
过滤：
GET /posts?status=published&author=John
7. 返回合适的 HTTP 状态码
根据操作结果返回标准状态码，增强 API 可预测性。
- 200 OK：请求成功
- 201 Created：资源创建成功
- 400 Bad Request：客户端输入错误
- 404 Not Found：资源不存在
- 401 Unauthorized：未认证
- 403 Forbidden：无权限访问
- 500 Internal Server Error：服务端异常
8. 统一响应格式
前后端交互应保持一致的数据结构。
{
"success": true,
"data": { ... },
"message": "获取成功"
}
// 错误时
{
"success": false,
"error": "用户不存在",
"code": 404
}
9. 使用 Router 模块化管理路由
将不同资源的路由拆分到独立文件，提高可维护性。
// routes/users.js
const express = require('express');
const router = express.Router();
router.get('/', getUsers);
router.get('/:id', getUserById);
module.exports = router;
<p>// app.js
app.use('/api/v1/users', userRouter);</p>基本上就这些常见规范，合理应用能让 Express 的 RESTful API 更专业、易用。
