JWT实现无状态认证与角色授权，URL路径法进行API版本控制，统一封装错误响应结构，并用OpenAPI自动生成文档与测试用例。
认证与授权：用JWT实现安全访问控制
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()})
API版本控制：URL路径法最直观可靠
版本控制不是可选项，而是演进必需。相比Header或参数方式，/v1/users/ 这类路径前缀更易调试、更易缓存、更易被文档工具识别。
立即学习“Python免费学习笔记（深入）”；
在Django REST Framework中，通过URLPathVersioning启用，并为不同版本注册独立视图集：
- v1路由指向稳定接口，字段名、状态码、分页格式保持兼容
- v2可引入新字段（如
full_name）、废弃旧字段（加deprecated=True标记）、或改用Cursor分页 - 所有响应头中显式返回
API-Version: v1，方便客户端感知当前版本
错误统一处理：让客户端快速定位问题
401、403、404这些状态码不能只靠HTTP默认语义，还要附带机器可读的code和人类可读的message。
推荐结构如下：
{
"code": "AUTH_TOKEN_EXPIRED",
"message": "登录已过期，请重新登录",
"details": {"timestamp": "2024-06-15T10:22:33Z"}
}
在框架层统一封装异常处理器，把PermissionDenied转成403+对应code，把ValidationError转成400+字段级错误列表。避免在业务代码里重复写return Response(..., status=400)。
实战小技巧：用OpenAPI自动生成文档与测试用例
别手写Swagger文档。用drf-spectacular（DRF）或fastapi.openapi（FastAPI）自动提取路由、序列化器、状态码和示例数据。
- 添加
@extend_schema手动补充业务约束，比如“仅企业用户可调用”或“email字段需经验证” - 导出
openapi.json后，可用curl或Postman一键导入，生成真实可运行的测试集合 - CI阶段跑
swagger-cli validate，确保API定义语法合法，防止文档与代码脱节
