api-design-restful

用途：为设计与实现 RESTful API 提供一套约定与代码模式，涵盖 URL 结构、响应格式、错误处理、校验、认证和限流。主要能力：资源化 URL（用名词复数，如 /api/v1/users），标准 HTTP 方法映射（GET 列表/详情、POST 创建、PUT 替换、PATCH 更新、DELETE 删除），嵌套资源，以及过滤、排序、分页查询（如 ?status=active&sort=-createdAt&page=2&limit=20）。统一响应结构：成功返回 { success: true, data, meta }，错误返回 { success: false, error: { code, message, details } }；错误码机器可读、message 人类可读、details 承载字段级错误。状态码约定：200/201/204 表示成功，400/401/403/404/409/422/429 表示客户端错误，500/503 表示服务端错误。使用方式：示例以 Express.js 为基座，含 asyncHandler 异步包装、控制器、错误处理中间件、Zod 校验中间件、JWT 认证与基于角色的授权、express-rate-limit 限流。安装命令与完整实现代码未在资料中提供。最佳实践：资源名用复数、首日即版本化（/api/v1/）、每次响应返回合适状态码、响应带 requestId 便于调试、用 OpenAPI/Swagger 文档化、列表接口分页、全站统一错误格式、记录带 correlation ID 的请求日志。限制：未提供具体安装步骤、依赖版本、测试方法或完整代码示例，落地时需按实际项目调整。