FastAPI的header全局登录验证/模拟请求示范

xiaotu

from typing import Annotated
from fastapi import FastAPI, Depends, Header, HTTPException, status


# 1. 编写自定义校验函数
# 这里的参数名会自动对应 HTTP 请求头 (Headers) 里的字段名
def verify_auth(
    username: Annotated[str, Header()], 
    token: Annotated[str, Header()]
):
    # 这里写你的校验逻辑，比如查询数据库或缓存
    # 假设正确的组合是 admin / secret123
    is_valid = (username == "admin" and token == "secret123")
    
    if not is_valid:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="用户名或 Token 错误，认证失败"
        )
    # 校验通过后，可以返回用户名，方便后续接口使用
    return username

# 2. 将校验函数设为全局依赖
# 这样整个 App 下的所有接口都会自动先跑这个函数
app = FastAPI(dependencies=[Depends(verify_auth)])

# --- 以下是接口示例 ---

@app.get("/data")
async def get_data():
    # 因为有全局依赖，只有验证通过才会进到这里
    return {"message": "认证成功，这是受保护的数据"}

@app.post("/upload")
async def upload_file():
    return {"message": "文件上传成功"}

# 如果某个接口需要知道当前是谁在操作，可以单独再接收一下
@app.get("/me")
async def read_current_user(username: Annotated[str, Depends(verify_auth)]):
    return {"current_user": username}

为什么这样写最简洁？
Header 自动提取：通过 Header()，FastAPI 会自动去请求头里找 username 和 token 字段，你不需要手动解析。

全局拦截：app.dependencies = [Depends(...)] 这一行代码，直接省去了在每个 def 后面写一遍验证的麻烦。

标准报错：使用 HTTPException 会自动返回标准的 JSON 格式，前端处理非常统一。

xiaotu

进阶：如果有个别接口“不需要”验证怎么办？
当你设置了 app.dependencies 全局验证后，所有接口都被锁死了。如果你有一个“登录”或“公开信息”接口需要绕过验证，可以这样做：

方案：使用 APIRouter 进行分组

from fastapi import APIRouter

# 1. 创建需要验证的路由组
secure_router = APIRouter(dependencies=[Depends(verify_auth)])

@secure_router.get("/items")
async def read_items():
    return [{"item": "Portal Gun"}]

# 2. 创建不需要验证的路由组（比如公开主页）
public_router = APIRouter()

@public_router.get("/home")
async def home():
    return {"message": "这是公开主页"}

# 3. 将它们注册到 app
app.include_router(secure_router)
app.include_router(public_router)

xiaotu

请求示范代码

import requests

# 1. 目标 URL
url = "http://127.0.0.1:8080/create-item"

# 2. 准备请求头 (Headers)
# 这里的 key 必须和你在 FastAPI verify_auth 函数中定义的变量名一致
# FastAPI 默认会将 username 识别为 header 中的 "username" 或 "user-name"
headers = {
    "username": "admin",
    "token": "secret123",
    "Content-Type": "application/json"
}

# 3. 准备 POST 发送的 JSON 数据
data = {
    "name": "测试商品",
    "price": 99.8
}

# 4. 发送请求
try:
    response = requests.post(url, json=data, headers=headers)
    
    # 5. 处理结果
    if response.status_code == 200:
        print("✅ 请求成功！")
        print("服务器响应:", response.json())
    elif response.status_code == 401:
        print("❌ 认证失败：用户名或 Token 错误")
    else:
        print(f"⚠️ 其他错误，状态码: {response.status_code}")
        print("详情:", response.text)

except Exception as e:
    print(f"🚀 连接服务器失败: {e}")

xiaotu

返回信息如何更规范。

短信验证码平台为假设示范

👉 场景 → HTTP 状态码 → 业务 code → 说明

给你一份可直接用来设计接口的清单（偏生产级）

✅ 一、基础设计原则（先定规则）

✔ HTTP 状态码（建议）

200：请求成功（即使业务失败也可以返回 200 + code）
400：参数错误
401：未认证（缺 token）
403：无权限 / token 错误
429：限流（非常重要）
500：服务器错误

✔ 业务 code（建议分段）

| 区间 | 含义 |
| --------- | ----- |
| 0 | 成功 |
| 1000₁₀₉₉ | 通用错误 |
| 1100₁₁₉₉ | 参数错误 |
| 1200₁₂₉₉ | 认证/权限 |
| 1300₁₃₉₉ | 短信发送 |
| 1400₁₄₉₉ | 验证码校验 |
| 1500₁₅₉₉ | 限流/风控 |

✅ 二、核心接口场景

📱 1. 发送验证码接口

✔ 成功

| HTTP | code | msg |
| ---- | ---- | ------- |
| 200 | 0 | success |

❌ 参数类

| HTTP | code | msg |
| ---- | ---- | ------- |
| 400 | 1101 | 手机号格式错误 |
| 400 | 1102 | 国家码错误 |
| 400 | 1103 | 缺少手机号 |
| 400 | 1104 | 模板ID无效 |

❌ 发送失败

| HTTP | code | msg |
| ---- | ---- | ------ |
| 200 | 1301 | 短信发送失败 |
| 200 | 1302 | 短信通道异常 |
| 200 | 1303 | 模板未审核 |
| 200 | 1304 | 内容违规 |

❌ 频控 / 风控（重点）

| HTTP | code | msg |
| ---- | ---- | --------- |
| 429 | 1501 | 请求过于频繁 |
| 429 | 1502 | 同一手机号发送过多 |
| 429 | 1503 | 同一IP发送过多 |
| 403 | 1504 | 风控拦截 |

❌ 账户问题

| HTTP | code | msg |
| ---- | ---- | ---------- |
| 403 | 1201 | API key 无效 |
| 403 | 1202 | 账户被禁用 |
| 200 | 1305 | 余额不足 |

🔐 2. 校验验证码接口

✔ 成功

| HTTP | code | msg |
| ---- | ---- | ---- |
| 200 | 0 | 验证成功 |

❌ 验证失败

| HTTP | code | msg |
| ---- | ---- | ------ |
| 200 | 1401 | 验证码错误 |
| 200 | 1402 | 验证码已过期 |
| 200 | 1403 | 验证码不存在 |
| 200 | 1404 | 验证码已使用 |

❌ 风控类

| HTTP | code | msg |
| ---- | ---- | ------ |
| 429 | 1505 | 验证次数过多 |
| 403 | 1506 | 风控限制 |

🧾 3. 通用认证错误（你现在做的）

| HTTP | code | msg |
| ---- | ---- | -------- |
| 401 | 1200 | 缺少认证信息 |
| 403 | 1201 | token 无效 |
| 403 | 1203 | token 过期 |
| 403 | 1204 | 权限不足 |

⚙️ 4. 系统级错误

| HTTP | code | msg |
| ---- | ---- | --------- |
| 500 | 1000 | 系统错误 |
| 500 | 1001 | Redis异常 |
| 500 | 1002 | DB异常 |
| 500 | 1003 | 第三方短信服务异常 |

🚫 5. 限流 / 防刷（非常关键）

| HTTP | code | msg |
| ---- | ---- | ----- |
| 429 | 1500 | 全局限流 |
| 429 | 1501 | 接口限流 |
| 429 | 1502 | 手机号限流 |
| 429 | 1503 | IP限流 |
| 429 | 1507 | 设备限流 |

🌍 6. 国际短信（可选）

| HTTP | code | msg |
| ---- | ---- | ------ |
| 400 | 1105 | 不支持该国家 |
| 200 | 1306 | 国际通道失败 |

✅ 三、推荐返回格式（最终统一）

{
  "code": 0,
  "msg": "success",
  "data": {
    "request_id": "xxxx",
    "expire_in": 300
  }
}

❌ 错误示例

{
  "code": 1502,
  "msg": "Too many requests",
  "data": null
}

HTTP：429

✅ 四、你这个项目建议“加几个关键字段”

短信系统建议返回：

{
  "code": 0,
  "msg": "success",
  "data": {
    "request_id": "abc123",
    "expire_in": 300,
    "retry_after": 60
  }
}

✅ 五、真实行业补充（很重要）

👉 大厂常见额外机制：

✔ 1. 图形验证码（防刷前置）

code: 1508

✔ 2. 滑块验证失败

code: 1509

✔ 3. 黑名单手机号

code: 1510

✅ 六、一句话总结

👉 短信平台的核心就是三块：

发送（1300段）
验证（1400段）
限流/风控（1500段） ← 最重要