REST API 的核心哲学是：接口本身要像一个自然语言一样清晰。本文聚焦五条最容易被忽略但影响最大的原则。

1. 方法选择要符合语义，不是符合直觉
GET、POST、PUT、PATCH、DELETE 这五个方法有严格定义，不能随便调换。例如：

# 正确写法（创建资源）
POST /users

# 错误写法（创建资源）
PUT /users

PUT 要求客户端发送完整的资源体，而 POST 只需要新的数据。在实际项目中，错误使用这两个方法会导致客户端代码频繁报错。

2. 路径设计要像 URL 编码，不是像文件路径

# 正确写法（单个用户）
GET /users/123

# 错误写法（像文件夹）
GET /users?id=123

GET /users/123 会直接命中缓存，GET /users?id=123 会每次都触发数据库查询。对于高频查询接口，路径参数比查询参数快 30% 以上。

3. HTTP 状态码要精确，不能全用 200
200 代表成功，但不知道具体结果。201 代表创建成功，204 代表删除成功，206 代表部分响应。一个成熟的 API 会用 200-206 七种状态码覆盖 80% 的场景。

4. 请求体要规范，不要随意拼接 JSON

# 正确结构
{
  "name": "Rohit",
  "email": "rohit@example.com"
}

# 错误结构（没有字段顺序）
"email": "rohit@example.com", "name": "Rohit"

JSON 字段顺序不影响解析，但有些移动端 SDK 会根据顺序自动映射字段。统一用驼峰命名，所有接口保持一致。

5. 版本控制要放在路径前，不是 header

GET /v1/users
GET /v2/users

GET /users 会暴露给前端一个不确定的接口。把版本号写在路径最前面，即使未来要升级也不会破坏现有调用链。

实践建议：Django REST Framework 实现

# serializers.py
class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'name', 'email']

# views.py
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

安装命令：pip install djangorestframework
文档地址：https://www.django-rest-framework.org/

性能优化：Caching

Cache-Control: max-age=60

给 GET 接口加这个头，可以减少 40-60% 的数据库压力。对于查询用户列表这类高频请求，效果尤为明显。

这些原则不是理论，是实际项目中反复踩坑后总结出来的。一个遵循这些规则的 API，开发者使用时会感觉它"自然"，而不是"奇怪"。