JWT实现无状态认证与角色授权，URL路径法进行API版本控制，统一封装错误响应结构，并用OpenAPI自动生成文档与测试用例。
API的安全核心在于区分“你是谁”和“你能做什么”。JWT（JSON Web Token）是Python API中主流的无状态认证方案，适合前后端分离和微服务场景。
使用PyJWT生成和验证Token，关键点有三个：
payload中放必要字段（如user_id、exp），避免敏感信息泄露SECRET_KEY）必须强随机且严格保密，生产环境建议从环境变量加载
检查exp、nbf和iss，并捕获ExpiredSignatureError等异常做友好返回授权则基于用户角色或权限标识，在请求进入业务逻辑前完成。例如用装饰器校验权限：
@require_permission('user:read')
def get_user(request):
return JsonResponse({'data': user.to_dict()})
版本控制不是可选项，而是演进必需。相比Header或参数方式，/v1/users/ 这类路径前缀更易调试、更易缓存、更易被文档工具识别。
在Django REST Framework中，通过URLPathVersioning启用，并为不同版本注册独立视图集：
full_name）、废弃旧字段（加deprecated=True标记）、或改用Cursor分页API-Version: v1，方便客户端感知当前版本401、403、404这些状态码不能只靠HTTP默认语义，还要附带机器可读的code和人类可读的message。
推荐结构如下：
{
"code": "AUTH_TOKEN_EXPIRED",
"message": "登录已过期，请重新登录",
"details": {"timestamp": "2025-06-15T10:22:33Z"}
}
在框架层统一封装异常处理器，把PermissionDenied转成403+对应code，把ValidationError转成400+字段级错误列表。避免在业务代码里重复写return Response(..., status=400)。
别手写Swagger文档。用drf-spectacular（DRF）或fastapi.openapi（FastAPI）自动提取路由、序列化器、状态码和示例数据。
@extend_schema手动补充业务约束，比如“仅企业用户可调用”或“email字段需经验证”openapi.json后，可用curl或Postman一键导入，生成真实可运行的测试集合swagger-cli validate，确保API定义语法合法，防止文档与代码脱节