RESTful API设计核心原则是用HTTP方法表达操作意图、资源路径名词化、准确使用状态码；Flask可快速搭建基础服务；JWT实现无状态认证；还需限流、参数校验、字段脱敏、日志记录和CORS配置。
RESTful API设计核心原则
RESTful不是一种技术，而是一套设计风格。关键在于用HTTP方法表达操作意图：GET获取资源、POST创建、PUT/PATCH更新、DELETE删除。资源路径要名词化，比如/users而不是/get_users；嵌套关系用层级表达，如/users/123/orders表示用户123的所有订单。
状态码必须准确：200表示成功获取，201用于创建成功并返回新资源位置，400代表客户端参数错误，401是未认证，403是无权限，404是资源不存在，500则是服务端异常。不要用200包所有响应，也不要靠返回体里的code字段掩盖真实状态。
用Flask快速搭建基础API服务
安装Flask后，一个极简的用户查询接口只需几行：
from flask import Flask, jsonify, request
app = Flask(__name__)
@app.route('/users/
def get_user(user_id):
# 这里查数据库或mock数据
return jsonify({'id': us
er_id, 'name': '张三', 'email': 'zhang@example.com'})
if __name__ == '__main__':
app.run(debug=True)
立即学习“Python免费学习笔记（深入）”；
注意：生产环境禁用debug=True；路由参数用
JWT认证实现流程
不依赖Session，适合分布式系统。用户登录时签发token，后续请求在Header中携带：Authorization: Bearer eyJhbGci...。服务端验证签名、过期时间、白名单（可选）后放行。
常用做法：
- 用PyJWT库生成和解码token，密钥存在环境变量中
- 登录接口返回包含access_token和expires_in的JSON，前端存入localStorage
- 保护接口前加装饰器，检查Header、解析token、注入user_id到request上下文
- 刷新机制可额外提供/refresh端点，用短期access_token+长期refresh_token组合
常见安全与工程细节
别让API裸奔。除了JWT，还要做这些：
- 限制请求频率：用flask-limiter按IP或用户ID控制每分钟调用次数
- 参数校验不能只靠前端：用marshmallow或pydantic定义Schema，自动过滤、转换、报错
- 敏感字段脱敏：返回用户信息时，自动隐藏password_hash、id_card等字段
- 日志记录关键行为：谁在什么时间调用了哪个接口、耗时多少、是否失败
- CORS配置要精确：开发时可用flask-cors全开，上线后只允许可信域名
接口文档建议用Swagger集成，Flask-RESTx或FastAPI原生支持，省去手写Markdown的麻烦。
