REST 核心原则

REST（Representational State Transfer）是一种软件架构风格，强调资源的状态转移。遵循 REST 规范可以提高 API 的可预测性和可扩展性。

一、资源命名规范

使用名词复数形式表示资源集合，如 /articles、/users；使用嵌套路径表示资源关系，如 /articles/1/comments；避免在 URL 中使用动词，操作通过 HTTP 方法表达。

二、HTTP 方法语义

GET：获取资源，幂等操作
POST：创建资源
PUT：完整更新资源
PATCH：部分更新资源
DELETE：删除资源

三、状态码规范

200 OK - 请求成功；201 Created - 资源创建成功；400 Bad Request - 请求参数错误；401 Unauthorized - 未认证；403 Forbidden - 无权限；404 Not Found - 资源不存在；500 Internal Server Error - 服务器错误。

四、版本控制

通过 URL 路径（/api/v1/articles）或请求头（Accept: application/vnd.api.v1+json）进行版本管理，确保向后兼容。

五、分页与过滤

使用查询参数实现分页（?page=1&limit=20）、排序（?sort=-created_at）和过滤（?status=published），返回元数据（total、pages）。