PythonAPI接口开发教程_RESTful设计与认证实践

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/‘, methods=[‘GET’])
def get_user(user_id):
  # 这里查数据库或mock数据
  return jsonify({‘id’: user_id, ‘name’: ‘张三’, ’email’: ‘zhang@example.com’})

if __name__ == ‘__main__’:
  app.run(debug=True)

立即学习“Python免费学习笔记（深入）”；

注意：生产环境禁用debug=True；路由参数用自动类型转换；jsonify自动设Content-Type为application/json并处理中文编码。

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的麻烦。