罗罗编程学习记录
本页内容 展开查看

04.7.15.4 安全认证与 OpenAPI 文档

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.15 FastAPI 框架

覆盖范围

  • OAuth2PasswordBearer、HTTPBearer、API Key、SecurityScopes 认证方案
  • JWT 结构、PyJWT 与 python-jose 差异、声明校验、过期刷新与黑名单
  • 密码哈希 passlib/bcrypt/argon2、盐值、时序攻击与常量时间比较
  • CORS 中间件细节、allow_credentials 陷阱、可信 Host、HTTPS 与 HSTS
  • OpenAPI 生成流程、openapi_url、自定义 openapi()、tags_metadata、summary/description
  • Swagger/ReDoc UI、include_in_schema、openapi_examples、responses 定制
  • 安全方案声明、scope 组合与依赖注入权限校验最佳实践
  • 密钥管理、审计日志、令牌存储风险与常见攻击防护

04.7.15.4-001 FastAPI 认证体系由哪些组件组成?

一句话结论

FastAPI 认证由三部分组成:安全方案对象(OAuth2PasswordBearer、HTTPBearer 等,描述凭证从哪里取)、依赖注入(Depends 把方案挂到路由,校验后返回当前用户)、OpenAPI 安全声明(方案自动写入文档的 securitySchemes)。认证逻辑复用普通依赖,不引入特殊装饰器。

概念解释

  • 安全方案只负责“提取凭证”,校验与用户加载在依赖函数里完成。
  • 方案对象可被多个路由共享,统一凭证来源与错误响应。

原理流程

  1. 实例化安全方案,指定凭证位置(头/查询参数/表单)。
  2. 编写依赖:从方案取 token → 校验 → 查用户 → 返回用户对象。
  3. 路由用 Depends 注入该依赖,未通过则抛 401/403。
  4. 方案元数据自动进入 OpenAPI 文档安全定义。

代码或图示

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="login")
app = FastAPI()

async def get_current_user(token: str = Depends(oauth2_scheme)):
    return verify_and_load(token)

@app.get("/me")
async def me(user=Depends(get_current_user)):
    return user

常见误区

  • 把安全方案当成认证本身:方案只提取 token,不校验签名与过期。
  • 每个路由重复写取 token 逻辑:应抽到共享依赖,便于统一改造。

追问

  • 认证失败默认返回什么?答:方案校验不到凭证时抛 401,权限不足在业务依赖里抛 403。
  • 安全方案会自动拦截未登录请求吗?答:不会,拦截发生在依赖校验抛错时。

04.7.15.4-002 OAuth2PasswordBearer 怎么工作,tokenUrl 有什么作用?

一句话结论

OAuth2PasswordBearer 从请求头 Authorization: Bearer <token> 提取 token;tokenUrl 只是文档元数据,告诉 Swagger UI 登录表单把账号密码 POST 到哪个地址换取 token,服务端校验逻辑不依赖它。未携带凭证时抛 HTTPException(401),可带 WWW-Authenticate 头。

概念解释

  • 它对应 OAuth2 密码模式(password flow)的 Bearer 令牌用法。
  • auto_error=False 时缺凭证返回 None,用于可选登录场景。

原理流程

  1. 方案被依赖调用,读取 Authorization 头。
  2. 头缺失或格式不符:auto_error=True 抛 401;否则返回 token 字符串。
  3. 依赖把 token 交给校验函数解析签名与声明。
  4. OpenAPI 按 tokenUrl 生成 OAuth2 password flow 定义。

代码或图示

oauth2_scheme = OAuth2PasswordBearer(
    tokenUrl="auth/login",
    scheme_name="Bearer",
    auto_error=True,
)

@app.post("/auth/login")
async def login(form: OAuth2PasswordRequestForm = Depends()):
    return {"access_token": create_token(form.username, form.password),
            "token_type": "bearer"}

常见误区

  • 以为 tokenUrl 会被框架调用去换 token:它只写进文档,登录端点要自己实现。
  • 用 OAuth2PasswordBearer 接 API Key:凭证位置语义不符,API Key 应用独立方案。

追问

  • OAuth2PasswordRequestForm 提供哪些字段?答:username、password、scope、grant_type 等表单字段。
  • 可选认证怎么写?答:auto_error=False,依赖内判断 token 是否为 None。

04.7.15.4-003 HTTPBearer 与 OAuth2PasswordBearer 有什么区别?

一句话结论

两者都从 Authorization: Bearer 头取凭证;HTTPBearer 对应 OpenAPI 的 HTTP Bearer 方案(描述为 bearer 认证),OAuth2PasswordBearer 对应 OAuth2 流程并携带 tokenUrl 等流程元数据。纯 Bearer token 校验场景用 HTTPBearer 更贴切,需要文档展示 OAuth2 登录表单时用 OAuth2PasswordBearer。

概念解释

  • OpenAPI 安全方案类型不同:http scheme 与 oauth2 flow。
  • 运行时提取行为基本一致,差别主要在文档表达。

原理流程

  1. 实例化对应方案,声明 bearer 格式与可选 realm。
  2. 依赖调用方案解析头,返回 HTTPAuthorizationCredentials 或 token 字符串。
  3. 校验凭证后返回用户。
  4. 文档按方案类型生成 securitySchemes 条目。

代码或图示

from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

bearer = HTTPBearer(auto_error=False)

@app.get("/secure")
async def secure(cred: HTTPAuthorizationCredentials = Depends(bearer)):
    token = cred.credentials if cred else None
    ...

常见误区

  • 以为两者运行时安全强度不同:校验强度取决于依赖内的签名/过期检查,与方案对象无关。
  • 混用导致文档出现两套相似方案:按实际协议选一种。

追问

  • HTTPAuthorizationCredentials 含哪些字段?答:scheme(如 bearer)与 credentials(令牌串)。
  • 自定义认证头(如 X-API-Key)用哪个?答:用 APIKeyHeader 或手写依赖读取头。

04.7.15.4-004 API Key 认证(Header/Query/Cookie)怎么实现?

一句话结论

FastAPI 提供 APIKeyHeader、APIKeyQuery、APIKeyCookie 方案,分别从请求头、查询参数、Cookie 提取 key;依赖内比对 key 与服务端存储的有效值,失败抛 401。API Key 适合服务间调用或简单内部接口,不适合面向浏览器的会话体系。

概念解释

  • API Key 通常长期有效,泄露后风险窗口大,需支持吊销与轮换。
  • 查询参数带 key 易进访问日志与浏览器历史,优先放头或 Cookie。

原理流程

  1. 实例化对应位置的 API Key 方案。
  2. 依赖提取 key,查配置/存储中的有效 key 集合。
  3. 校验通过返回调用方身份,否则 401。
  4. 方案写入 OpenAPI securitySchemes。

代码或图示

from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)

async def get_app_key(key: str | None = Depends(api_key_header)):
    if not key or key not in valid_keys:
        raise HTTPException(status_code=401, detail="invalid api key")
    return key

常见误区

  • 把 API Key 放 URL 查询参数:日志、历史、Referer 都可能记录。
  • 硬编码 key 列表在源码:应走配置/密钥管理,支持轮换与吊销。

追问

  • API Key 与 JWT 怎么选?答:服务间机器身份用 API Key/客户端凭证;面向用户的登录态用 JWT/会话。
  • 多个 key 怎么管理?答:带 key ID(kid)便于定位调用方、单独吊销与审计。

04.7.15.4-005 SecurityScopes 是什么,如何声明与读取?

一句话结论

SecurityScopes 承载当前请求被要求的权限范围列表;安全方案在实例化时声明 scopes,依赖内可读取 security_scopes.scopes 与 token 实际携带的 scope 做比对。scope 用于细粒度授权(如 read:items、write:items),并在 OpenAPI 文档中按方案分组展示。

概念解释

  • scope 是 OAuth2 体系的授权范围声明,介于“登录与否”和“角色”之间。
  • 方案声明的 scope 是该路由要求的集合,token 内 scope 是用户实际授予的集合。

原理流程

  1. 实例化方案时传入 scopes=[Scope(...)]。
  2. 依赖注入 SecurityScopes,读取要求范围。
  3. 解析 token 得到授予范围,做包含校验。
  4. 文档把 scope 挂到对应安全方案下。

代码或图示

from fastapi import Security, SecurityScopes

oauth2 = OAuth2PasswordBearer(tokenUrl="login", scopes={
    "read:items": "读取商品",
    "write:items": "写入商品",
})

async def get_current_user(
    security_scopes: SecurityScopes,
    token: str = Depends(oauth2),
):
    payload = decode(token)
    for scope in security_scopes.scopes:
        if scope not in payload.get("scopes", []):
            raise HTTPException(403, "scope 不足")
    return load_user(payload["sub"])

@app.get("/items", dependencies=[Security(get_current_user, scopes=["read:items"])])
def list_items():
    ...

常见误区

  • 只校验 token 有效,不比对 scope:登录用户越权访问受限接口。
  • 把角色塞进 scope 字符串随意命名:scope 应稳定、可枚举、文档化。

追问

  • Security 与 Depends 在安全场景有何不同?答:Security 支持声明路由级 scopes,语义上表达安全依赖,运行时同样走依赖注入。
  • scope 不足返回什么状态码?答:403 Forbidden;未认证返回 401。

04.7.15.4-006 认证依赖如何返回当前用户模型而不只是 token?

一句话结论

依赖函数完成“取 token → 校验签名与声明 → 查库加载用户 → 状态校验”后返回用户模型实例;路由参数类型标注为用户模型,框架按类型注入。这样业务代码直接拿到用户对象,不必重复解析 token。

概念解释

  • 用户模型可含 ID、角色、scope、状态等字段,供授权与业务使用。
  • 查库失败、用户禁用、token 过期都在依赖内转成对应 HTTP 错误。

原理流程

  1. 安全方案提取凭证字符串。
  2. 校验签名、过期、签发方等声明。
  3. 按 sub 查用户,校验账号状态。
  4. 返回用户模型;任一环节失败抛 401/403。

代码或图示

async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
    try:
        payload = jwt.decode(token, SECRET, algorithms=[ALG])
    except JWTError:
        raise HTTPException(401, "invalid token",
                            headers={"WWW-Authenticate": "Bearer"})
    user = await user_repo.get(payload["sub"])
    if user is None or not user.active:
        raise HTTPException(401, "user unavailable")
    return user

@app.get("/me")
async def me(user: User = Depends(get_current_user)):
    return user

常见误区

  • 依赖只返回 payload dict:业务层到处重复取 sub、判空,类型也不安全。
  • 不在依赖里校验用户状态:已禁用用户凭旧 token 继续访问。

追问

  • 依赖返回的用户对象能在响应模型里序列化吗?答:注意排除密码哈希等敏感字段,用独立响应模型。
  • 加载用户走同步 ORM 怎么办?答:同步查询包线程池,或改用异步驱动。

04.7.15.4-007 JWT 的结构是怎样的?

一句话结论

JWT 由三段 Base64URL 编码组成:header(算法与类型)、payload(声明,如 sub、exp、iss、aud、scopes)、signature(用 header 指定算法对前两段签名)。三段以点分隔,header/payload 可被解码查看,签名只保证完整性与来源,不提供加密保密。

概念解释

  • 常见声明:sub 用户标识、exp 过期时间、iat 签发时间、iss 签发方、aud 受众、nbf 生效时间。
  • JWT 是自包含令牌,服务端校验签名即可,不必每次查会话存储。

原理流程

  1. 头部声明 alg(如 HS256)与 typ: JWT。
  2. 载荷写入业务声明与过期时间。
  3. 用密钥按算法对 header.payload 计算签名。
  4. 服务端解码后用同密钥/公钥验签,再检查声明有效性。

代码或图示

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM...}.signature
└── header ──────────────────────────────┘ └── payload ──┘ └ sig ┘

常见误区

  • 以为 JWT 内容加密:payload 是 Base64 编码,任何人可解码,不能放密码、敏感个人信息。
  • 把大对象塞进 token:体积变大,占用头带宽并可能触发代理/网关长度限制。

追问

  • 签名算法 HS256 与 RS256 区别?答:HS256 对称密钥签名验签;RS256 私钥签名、公钥验签,适合多服务共享。
  • JWT 为什么适合无状态认证?答:凭证自包含,验签即可识别身份,无需服务端查会话表。

04.7.15.4-008 PyJWT 与 python-jose 有什么差异,怎么选型?

一句话结论

PyJWT(import jwt)接口轻量,覆盖常见 HS/RS/ES 算法与声明校验;python-jose(from jose import jwt)兼容 JOSE 规范,支持 JWKS、更多曲线与加密场景,FastAPI 官方教程历史上采用 python-jose。新项目纯对称签名场景可选 PyJWT;需要 JWKS 验签、跨服务公钥分发时评估 jose。

概念解释

  • 两者 API 接近:encode(payload, key, algorithm=...)、decode(token, key, algorithms=[...])。
  • 依赖选型要结合团队维护、安全补丁与目标算法支持。

原理流程

  1. 按算法与密钥形态选择库。
  2. 签发:构造 payload,指定算法与密钥生成 token。
  3. 验签:传入允许的算法白名单与密钥,解码并校验声明。
  4. 验签失败抛库特定异常,依赖转成 401。

代码或图示

# PyJWT
import jwt
token = jwt.encode({"sub": uid}, SECRET, algorithm="HS256")
payload = jwt.decode(token, SECRET, algorithms=["HS256"])

# python-jose
from jose import jwt, JWTError
payload = jwt.decode(token, SECRET, algorithms=["HS256"])

常见误区

  • 混用两个库的异常类型:捕获异常要对应实际依赖库,避免漏捕验签失败。
  • 不限制 algorithms 白名单:验签时接受攻击者指定的弱算法。

追问

  • 两个库都要装吗?答:按项目实际选一个,避免重复依赖与行为差异。
  • JWKS 验签哪个更方便?答:jose 对 JWK/JWKS 支持更完整(待确认:验证点:所用库版本对目标算法与 JWKS 的支持矩阵)。

04.7.15.4-009 JWT 校验要检查哪些声明?

一句话结论

验签通过后必须检查:exp(未过期)、nbf(已生效)、iss(签发方可信)、aud(受众匹配本服务);按需检查 iat 时间合理性与 sub 存在性。算法白名单在 decode 的 algorithms 参数中固定,不接受 token 头部指定的算法。

概念解释

  • 签名有效只证明 token 未被篡改且来自持密钥方,不代表业务上仍有效。
  • 时钟偏移要考虑:服务节点时间不同步可能误判过期,库一般支持 leeway 参数。

原理流程

  1. 用密钥与算法白名单验签,签名失败即拒。
  2. 校验 exp/nbf 时间声明。
  3. 校验 iss/aud 与本服务配置匹配。
  4. 加载 sub 对应用户并检查状态。

代码或图示

payload = jwt.decode(
    token, SECRET,
    algorithms=["HS256"],
    issuer="https://api.example.com",
    audience="web-app",
    options={"require": ["exp", "sub"]},
    leeway=30,
)

常见误区

  • 只验签名不查过期:被窃取的旧 token 长期可用。
  • aud/iss 不校验:A 服务签发的 token 可能被 B 服务接受。

追问

  • options={"verify_exp": False} 什么时候用?答:仅调试场景,生产必须开启过期校验。
  • 节点时钟不同步怎么办?答:部署 NTP 对时,验签留小 leeway 缓冲。

04.7.15.4-010 JWT 过期处理与刷新令牌机制怎么设计?

一句话结论

访问令牌(access token)寿命短(分钟级),过期后客户端用刷新令牌(refresh token)换取新 access token;刷新令牌寿命更长、可吊销,通常单独存储并绑定设备/客户端。短 access token 缩小泄露窗口,refresh token 提供续期与退出控制。

概念解释

  • 双令牌结构:access 进 Authorization 头,refresh 存 HttpOnly Cookie 或安全存储。
  • 刷新端点校验 refresh 有效性后重签 access,可同时轮换 refresh。

原理流程

  1. 登录成功签发短寿命 access 与长寿命 refresh。
  2. 业务接口 access 过期返回 401,客户端调刷新端点。
  3. 校验 refresh 签名、过期、吊销状态与绑定关系。
  4. 签发新 access(必要时轮换 refresh),旧 refresh 作废。

代码或图示

@app.post("/auth/refresh")
async def refresh(refresh_token: str = Depends(refresh_scheme)):
    payload = verify_refresh(refresh_token)
    new_access = create_access_token(payload["sub"], payload["scopes"])
    return {"access_token": new_access, "token_type": "bearer"}

常见误区

  • access token 设成几天有效:泄露后不可吊销,窗口过大。
  • refresh token 与 access token 同寿命同存储:失去双令牌分层意义。

追问

  • 刷新令牌放哪里更安全?答:浏览器场景优先 HttpOnly Secure Cookie;前端内存存储 access 配合缓解 XSS 读取风险。
  • refresh 也要校验黑名单吗?答:要,登出/改密/设备下线时把 refresh 加入吊销列表。

04.7.15.4-011 令牌黑名单与服务端吊销怎么实现?

一句话结论

JWT 默认无状态,签发后到期前无法作废;需要主动吊销时,用 Redis/DB 维护吊销列表(按 jti 或用户 ID+版本),验签后检查是否在黑名单或版本已轮换。登出、改密、权限变更、设备下线都应触发吊销。

概念解释

  • 黑名单条目 TTL 设为剩余有效期,避免存储无限增长。
  • 用户级版本号(如 token_version)可一次吊销某用户全部旧令牌。

原理流程

  1. 签发时写入唯一 jti 与用户 token 版本。
  2. 登出/下线时把 jti 或版本号加入存储,设 TTL。
  3. 校验时先验签,再查黑名单/版本是否失效。
  4. 命中即拒,返回 401 并清理客户端凭证。

代码或图示

async def is_revoked(jti: str, user_id: str) -> bool:
    return await redis.sismember(f"revoked:{user_id}", jti)

# 用户级批量吊销:递增版本号,旧 token 版本不符即拒
async def rotate_tokens(user_id: str):
    await redis.incr(f"token_version:{user_id}")

常见误区

  • 以为 JWT 登出后服务端就失效:不查黑名单时,旧 token 到期前仍可用。
  • 黑名单永久保留:内存/存储随时间膨胀,应按 TTL 自动过期。

追问

  • 分布式吊销列表放哪里?答:Redis 等共享存储,各实例校验时统一查询。
  • 大用户批量下线怎么做?答:用 token 版本号/角色版本号,避免逐条写黑名单。

04.7.15.4-012 JWT 不适合存什么数据,为什么?

一句话结论

JWT payload 可被任何人 Base64 解码,不能存密码、哈希、身份证号、手机号等敏感信息;也不适合放频繁变更的状态(如权限列表、余额),否则旧令牌携带过期授权。令牌内只放稳定标识与必要 scope。

概念解释

  • 保密性与完整性是两回事:签名防篡改,不防读取。
  • 授权变更要生效,需要吊销旧令牌或等待其过期。

原理流程

  1. 签发前审查 payload 字段,剥离敏感与易变数据。
  2. 身份类信息(sub、scopes)放令牌。
  3. 业务状态在请求到达后查库获取。
  4. 权限变更走吊销/版本轮换机制。

代码或图示

# 不推荐
{"sub": "u1", "password_hash": "...", "phone": "138...", "roles": [...]}
# 推荐
{"sub": "u1", "scopes": ["read:items"], "jti": "..."}

常见误区

  • 把整份用户对象序列化进 token:体积大且权限变更后旧 token 仍有效。
  • 依赖 token 内角色做最终授权:敏感操作应实时查库复核。

追问

  • 需要加密 payload 怎么办?答:使用 JWE(加密 JWT)方案并评估库支持;常规接口仍以服务端查库为准。
  • token 太长有什么问题?答:请求头增大,可能被代理/CDN 限制,移动端占用更多流量。

04.7.15.4-013 密码哈希为什么不能用 MD5/SHA256 直接存?

一句话结论

MD5、SHA256 是快速哈希,设计目标是校验完整性;GPU/ASIC 可高速暴力枚举常见密码,彩虹表反查成本低。存储密码必须用专门的慢哈希算法(bcrypt、argon2、PBKDF2),通过工作因子拉长单次计算成本,并带随机盐。

概念解释

  • 快速哈希让“猜密码”也变快,与存储安全目标相反。
  • 慢哈希可调成本:随硬件升级提高迭代次数/内存参数。

原理流程

  1. 注册时生成随机盐,用慢哈希计算密码摘要。
  2. 存储哈希与算法参数,不存明文与盐副本(盐通常编码在哈希串内)。
  3. 登录时用相同盐与参数重算,常量时间比对。
  4. 暴力破解单次成本被工作因子拉高。

代码或图示

# 不推荐:快速哈希
hashlib.sha256(password.encode()).hexdigest()

# 推荐:慢哈希(argon2/bcrypt/passlib 封装)
hash = pwd_context.hash(password)
ok = pwd_context.verify(password, hash)

常见误区

  • 自己“加盐”后用 SHA256:依然是快速哈希,抗暴力能力不足。
  • 哈希后再多层普通哈希:不增加慢哈希的工作因子,实现复杂度高且易错。

追问

  • 彩虹表为什么被盐抵消?答:每个用户盐不同,预计算表无法复用反查。
  • 慢哈希会不会拖垮登录接口?答:单次毫秒级,可叠加登录限流保护,必要时限流在线程池执行。

04.7.15.4-014 passlib、bcrypt、argon2 各自有什么特点?

一句话结论

passlib 是哈希封装库,统一接口并支持多种后端与算法识别;bcrypt 是成熟慢哈希,自适应成本因子,实现广泛兼容;argon2 是密码哈希竞赛冠军方案,可调内存、迭代度与并行度,抗 GPU/ASIC 攻击能力强。新项目优先 argon2,存量系统常见 bcrypt。

概念解释

  • passlib 不自己实现算法,调用底层后端(bcrypt、argon2_cffi 等)。
  • 算法选择要考虑依赖维护、部署环境与历史数据迁移。

原理流程

  1. 注册:按选定算法与参数计算哈希串(含盐与成本参数)。
  2. 校验:从哈希串解析参数,重算并比对。
  3. 算法升级:登录校验通过后可用新参数重哈希(rehash)平滑迁移。
  4. 配置记录所用算法,便于后续调参与迁移。

代码或图示

from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["argon2"], deprecated="auto")

def hash_password(pw: str) -> str:
    return pwd_context.hash(pw)

def verify_password(pw: str, hashed: str) -> bool:
    return pwd_context.verify(pw, hashed)

常见误区

  • 只装 passlib 不装后端:调用对应算法时报后端缺失。
  • 固定过低成本因子:硬件升级后哈希变弱;过高则登录延迟与 CPU 压力上升。

追问

  • argon2 三个参数调什么?答:内存成本(memory_cost)、迭代次数(time_cost)、并行度(parallelism),按服务承受的单次延迟调整。
  • 旧 bcrypt 哈希怎么迁到 argon2?答:登录校验通过后按新算法 rehash 覆盖,不必一次性批量改库。

04.7.15.4-015 bcrypt 的 72 字节限制怎么处理?

一句话结论

bcrypt 算法只取密码前 72 字节参与计算,超出部分被忽略;长密码需要先做一次 SHA-256 预哈希(把摘要作为输入)再喂给 bcrypt,或改用无此限制的 argon2。存储与校验使用同一预处理流程,避免前后不一致。

概念解释

  • 72 字节限制来自算法内部设计,不是 passlib 封装问题。
  • 预哈希要在服务端固定实现,不能依赖客户端行为。

原理流程

  1. 注册:密码先经 SHA-256 摘要,再交 bcrypt 哈希。
  2. 登录:相同预处理后重算比对。
  3. 超长密码不受截断影响。
  4. 更换算法时同步调整预处理流程。

代码或图示

import hashlib

def bcrypt_hash(pw: str) -> str:
    digest = hashlib.sha256(pw.encode()).digest()
    return pwd_context.hash(digest)

def bcrypt_verify(pw: str, hashed: str) -> bool:
    digest = hashlib.sha256(pw.encode()).digest()
    return pwd_context.verify(digest, hashed)

常见误区

  • 直接把超长密码交给 bcrypt:72 字节之后内容不参与哈希,等效弱口令。
  • 注册与登录预处理不一致:合法用户也校验失败。

追问

  • 不预哈希还有别的选择吗?答:换用 argon2 等无 72 字节截断限制的算法。
  • 预哈希会降低安全性吗?答:只要流程固定、盐仍由慢哈希提供,整体抗暴力能力由慢哈希工作因子保证。 '@

04.7.15.4-016 什么是时序攻击,密码与令牌比对为什么要常量时间?

一句话结论

时序攻击通过测量比对耗时推断匹配前缀长度:普通字符串比较在首个不匹配字节处提前返回,耗时随匹配位数变化。密码哈希、API Key、签名比对必须用常量时间比较(如 hmac.compare_digest),使耗时与匹配程度无关,避免侧信道泄露。

概念解释

  • 侧信道不依赖攻破算法,而依赖运行行为(耗时、响应差异)。
  • 网络噪声会降低远程时序攻击精度,但本地与内网场景仍需防护。

原理流程

  1. 攻击者提交逐位变化的凭证,测量响应耗时。
  2. 普通比较在失配处短路返回,匹配位越多耗时略长。
  3. 据此逐位推断有效前缀。
  4. 常量时间比较遍历全部字节,耗时不随匹配度变化。

代码或图示

import hmac

def safe_equals(a: str, b: str) -> bool:
    return hmac.compare_digest(a.encode(), b.encode())

# 哈希库的 verify 内部通常已是常量时间实现,不要改用 == 手比

常见误区

  • 用 == 比对 token/key:字符串短路比较存在时序差异。
  • 以为远程攻击不可行就忽略:内网、同机部署与批量探测场景仍有风险。

追问

  • compare_digest 支持哪些类型?答:str(ASCII)与 bytes,长度不同直接返回不等。
  • 慢哈希 verify 内部安全吗?答:成熟库的 verify 走常量时间比对,不要绕过它自行 ==。

04.7.15.4-017 注册与登录的密码校验流程怎么写?

一句话结论

注册:校验密码强度 → 慢哈希后入库,绝不存明文;登录:按用户名取记录 → 用同一哈希参数 verify 比对 → 成功签发令牌,失败返回统一错误(不区分“用户不存在”与“密码错误”)。哈希计算放线程池,避免阻塞事件循环。

概念解释

  • 统一登录失败消息防止用户名枚举;响应时序也应尽量一致。
  • 密码字段在用户模型与响应模型中排除,避免回传。

原理流程

  1. 注册:强度校验 → pwd_context.hash → 存哈希串。
  2. 登录:查用户 → verify 比对哈希。
  3. 校验通过生成 access/refresh;失败抛 401 统一消息。
  4. 记录登录审计(成功/失败、来源 IP、时间)。

代码或图示

@app.post("/auth/register")
async def register(user: UserCreate):
    hashed = await run_in_threadpool(pwd_context.hash, user.password)
    await user_repo.create(user.username, hashed)
    return {"ok": True}

@app.post("/auth/login")
async def login(form: OAuth2PasswordRequestForm = Depends()):
    user = await user_repo.get_by_name(form.username)
    valid = bool(user) and await run_in_threadpool(
        pwd_context.verify, form.password, user.hashed_password)
    if not valid:
        raise HTTPException(401, "用户名或密码错误")
    return {"access_token": create_token(user.id), "token_type": "bearer"}

常见误区

  • 登录时分别提示“用户不存在”和“密码错误”:泄露已注册用户名。
  • 同步慢哈希直接在 async def 端点调用:哈希计算阻塞事件循环,应包线程池。

追问

  • 密码强度怎么校验?答:长度、字符类别、常见弱口令黑名单,可复用 zxcvbn 类库(按项目依赖确认)。
  • 首次登录强制改密怎么做?答:用户记录标记 must_change_password,登录后校验拦截。

04.7.15.4-018 随机盐如何防护彩虹表与同密码碰撞?

一句话结论

盐是注册时生成的随机值,与密码一起送入慢哈希;同一密码在不同用户名下产生不同哈希,预计算的彩虹表无法复用反查。盐不需要保密,通常编码在哈希串内随哈希一起存储;关键是每个用户独立、足够随机。

概念解释

  • 盐防“批量反查”,慢哈希防“单条暴力”,两者互补。
  • 盐长度不足或可预测会削弱防护,应使用密码学随机源生成。

原理流程

  1. 注册生成随机盐(库内部自动完成)。
  2. 盐 + 密码经慢哈希得到摘要,盐与参数编码进哈希串。
  3. 登录从哈希串解析盐与参数,重算比对。
  4. 相同密码因盐不同得到不同存储值。

代码或图示

hash = Argon2(salt=random_salt).hash(password)
存储:$argon2id$v=19$m=65536,t=3,p=4$<salt>$<hash>

常见误区

  • 所有用户共用一个固定盐:彩虹表只需针对该盐预计算一次。
  • 盐存别处且与哈希分离:任一泄露都破坏隔离,同库存储是常规做法。

追问

  • 盐能防止同一个人复用弱密码吗?答:不能阻止用户自己选弱密码,需强度策略约束。
  • 慢哈希库里盐是自动生成的吗?答:是,封装库在 hash 时生成随机盐并编码进结果串。

04.7.15.4-019 CORS 中间件参数逐项说明

一句话结论

CORSMiddleware 核心参数:allow_origins(允许的源列表,含协议/域名/端口)、allow_methods(允许的 HTTP 方法)、allow_headers(允许的请求头)、allow_credentials(是否携带 Cookie/凭证)、expose_headers(前端可读的响应头)、max_age(预检结果缓存秒数)。参数按白名单显式配置,不盲目放开。

概念解释

  • CORS 是浏览器安全机制,服务端通过响应头告诉浏览器哪些跨源页面可访问。
  • 非浏览器客户端(服务间调用)不受 CORS 约束,不要把 CORS 当访问控制。

原理流程

  1. 浏览器请求带 Origin,中间件比对白名单。
  2. 命中则在响应追加 Access-Control-Allow-Origin 等头。
  3. 复杂请求先发 OPTIONS 预检,中间件回应方法/头/凭证许可。
  4. 预检通过后浏览器才发送实际请求。

代码或图示

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://web.example.com"],
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Authorization", "Content-Type"],
    allow_credentials=True,
    expose_headers=["X-Request-ID"],
    max_age=600,
)

常见误区

  • 把 CORS 当鉴权:绕过浏览器直接调接口不受 CORS 限制,鉴权必须在依赖层做。
  • allow_methods/allow_headers 写 ["*"] 后又开凭证:与凭证规则冲突(见下题)。

追问

  • 源为什么要带协议和端口?答:同源判定按 scheme + host + port,任一不同即跨源。
  • 开发环境怎么放宽?答:按环境配置 origins,本地可列开发地址,生产必须白名单。

04.7.15.4-020 allow_credentials=True 与 allow_origins=["*"] 有什么陷阱?

一句话结论

开启凭证后,Access-Control-Allow-Origin 不能返回通配符 *,必须回显具体请求源;同时 Access-Control-Allow-Credentials: true。若 allow_origins=["*"] 又 allow_credentials=True,浏览器会拒绝带凭证的跨源请求。生产配置要列具体源,不能用通配符图省事。

概念解释

  • 凭证场景(Cookie、Authorization、客户端证书)下,浏览器强制要求精确源匹配。
  • 中间件在凭证开启时会按请求源回显,而不是发 *。

原理流程

  1. 配置凭证开启,源白名单为具体域名。
  2. 预检/实际请求带来源头,中间件命中后回显该源。
  3. 响应同时带允许凭证标记。
  4. 通配符 + 凭证组合被浏览器拦截,前端表现为跨域报错。

代码或图示

# 错误组合:凭证开启 + 通配符源
# CORSMiddleware(allow_origins=["*"], allow_credentials=True)

# 正确:具体源,按需回显
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_credentials=True,
)

常见误区

  • 以为把 origins 设 ["*"] 就能兼容所有前端:凭证接口在浏览器里直接不可用。
  • 源列表写局域网/内网通配:内部页面也能带凭证访问,扩大攻击面。

追问

  • 不带凭证可以用 * 吗?答:公开只读接口可以,allow_origins=["*"] 配合不开凭证。
  • 多前端域名怎么配?答:枚举各域名,必要时按环境分组配置。

04.7.15.4-021 CORS 预检请求(OPTIONS)是怎么处理的?

一句话结论

浏览器对“复杂请求”(自定义头、非简单方法、JSON 等)先发 OPTIONS 预检,询问服务端允许的方法、头与凭证;CORSMiddleware 识别 OPTIONS 与 Access-Control-Request-Method/Headers,返回预检响应头并短路,不进入业务路由。预检结果由 max_age 缓存。

概念解释

  • 简单请求(GET/POST/HEAD + 表单/文本头)不发预检,直接发实际请求。
  • 预检不带业务凭证语义,处理不当会导致真实请求被浏览器阻止。

原理流程

  1. 浏览器判断请求为复杂类型,先发 OPTIONS。
  2. 中间件提取请求方法/头,比对白名单。
  3. 返回 Access-Control-Allow-Methods/Headers/Origin/Credentials,状态 200/204。
  4. 预检通过后发送实际请求;缓存期内不再预检。

代码或图示

OPTIONS /items
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization,content-type
→ 204 + Access-Control-Allow-* 响应头

常见误区

  • 业务路由里手写 OPTIONS 处理:与中间件重复,头容易配错。
  • 预检被认证依赖拦截:OPTIONS 未带 token 时返回 401,浏览器判定跨域失败;认证依赖应放行预检或由中间件先处理。

追问

  • 为什么预检请求常被 401 挡住?答:认证逻辑跑在中间件内层,OPTIONS 未通过鉴权,跨域头无法返回。
  • max_age 设多少合适?答:数百秒到十分钟,减少重复预检;过长会在配置变更后延迟生效。

04.7.15.4-022 可信 Host 校验与反向代理 Host 头怎么处理?

一句话结论

可信 Host 校验限制只接受白名单内的 Host 头,防止 Host 头注入(密码重置链接、缓存投毒、路由绕过)。部署在 Nginx/网关后时,要配置代理转发真实 Host(X-Forwarded-Host)并在应用层信任链路上的代理,避免校验误拦或被伪造头欺骗。

概念解释

  • Starlette 提供 TrustedHostMiddleware 做 Host 白名单。
  • 代理链中应用看到的 Host 取决于转发配置,需要统一约定。

原理流程

  1. 配置 Host 白名单(域名列表,支持通配规则按实现确认)。
  2. 请求进入中间件,比对 Host 头与白名单。
  3. 不匹配返回 400,不进入业务。
  4. 反代层正确传递 Host/X-Forwarded-Host,应用只信任该链路。

代码或图示

from starlette.middleware.trustedhost import TrustedHostMiddleware

app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["api.example.com", "internal.example.com"],
)

常见误区

  • 生产关闭 Host 校验:攻击者伪造 Host 影响生成链接与缓存键。
  • 直接信任客户端传入的 X-Forwarded-Host:必须确认前置代理已剥离外部伪造值。

追问

  • 健康检查/内部调用 Host 不同怎么办?答:白名单纳入内部域名或允许内部网段来源的主机头。
  • 子域名通配怎么写?答:按中间件实现支持的通配语法配置(待确认:验证点:Starlette 0.4x TrustedHostMiddleware 通配规则)。

04.7.15.4-023 生产环境如何强制 HTTPS 并配置 HSTS?

一句话结论

生产由反代/网关终止 TLS,应用内部 HTTP 仅走可信内网;通过重定向把 HTTP 访问升级到 HTTPS,响应加 Strict-Transport-Security(HSTS)告知浏览器后续强制走 HTTPS。HSTS 只应在确认全站 HTTPS 后开启,必要时先用短 max-age 观察。

概念解释

  • HSTS 是浏览器侧策略,一旦生效,用户在期限内无法跳过 HTTPS。
  • 证书、TLS 版本与套件在代理/负载均衡层管理,应用不重复终止。

原理流程

  1. 代理监听 80/443,80 跳转 443。
  2. HTTPS 响应追加 HSTS 头(max-age、可选 includeSubDomains、preload)。
  3. 浏览器记住策略,后续直接 HTTPS 访问。
  4. 应用通过 X-Forwarded-Proto 判断原始协议,生成正确绝对链接。

代码或图示

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

常见误区

  • 全站未稳定 HTTPS 就开长周期 HSTS:配置出问题后浏览器侧难以及时回退。
  • 应用依赖请求协议判断站点地址:反代后需读取 X-Forwarded-Proto 并信任代理链。

追问

  • HSTS 与 HTTPS 重定向有什么区别?答:重定向是每次跳转;HSTS 让浏览器记住策略,减少明文访问。
  • preload 提交要注意什么?答:所有子域名必须长期支持 HTTPS,否则被浏览器内置策略阻断。

04.7.15.4-024 OpenAPI 文档是怎么生成出来的?

一句话结论

FastAPI 遍历路由与依赖签名:从路径参数、查询参数、请求体模型、响应模型、安全方案提取类型与约束,按 OpenAPI 规范组装成 JSON schema;/openapi.json 暴露该文档,Swagger UI 与 ReDoc 读取它渲染页面。模型字段约束(类型、必填、范围、示例)直接成为 schema 定义。

概念解释

  • 生成基于 Python 类型标注与 Pydantic 模型,不需要手写接口描述。
  • 依赖中的参数同样会进入文档(除非隐藏)。

原理流程

  1. 应用启动后收集全部路由的路径、方法、处理器引用。
  2. 解析函数签名与依赖,提取参数来源(path/query/body/header/cookie)。
  3. 用 Pydantic 模型生成 JSON Schema,组合安全方案与响应声明。
  4. 汇总成 OpenAPI 对象,openapi_url 暴露 JSON,UI 页面加载渲染。

代码或图示

路由签名 + Pydantic 模型
  → 参数/响应 schema 提取
  → securitySchemes 合并
  → /openapi.json
  → Swagger UI / ReDoc 渲染

常见误区

  • 以为文档需要单独维护:改模型与签名即自动反映到文档。
  • 依赖里混入敏感内部参数:未隐藏时会出现在公开文档中。

追问

  • OpenAPI 版本默认是多少?答:FastAPI 0.11x 默认生成 OpenAPI 3.x(待确认:验证点:所用版本的具体 OpenAPI minor 版本)。
  • 文档 schema 与实际响应不一致常见原因?答:返回 dict 未声明响应模型,或模型字段与序列化输出脱节。

04.7.15.4-025 openapi_url、docs_url、redoc_url 如何配置,如何关闭文档?

一句话结论

应用构造参数:openapi_url 指定 schema JSON 路径(/openapi.json),docs_url 指定 Swagger UI 路径(/docs),redoc_url 指定 ReDoc 路径(/redoc);传 None 即可关闭对应页面/JSON。生产可按环境关闭外部文档,或加内网认证保护。

概念解释

  • 关闭 docs_url 不等于关闭 openapi_url:schema JSON 仍可能被访问,需同时处理。
  • 多应用挂载时各实例有独立文档路径。

原理流程

  1. 构造 FastAPI(...) 时传入文档路径或 None。
  2. 框架按配置注册文档路由。
  3. 访问对应路径返回 UI 或 schema。
  4. 生产环境按部署策略关闭或保护文档入口。

代码或图示

app = FastAPI(
    title="Admin API",
    openapi_url="/openapi.json",
    docs_url="/docs",
    redoc_url="/redoc",
)

# 关闭文档(仅保留 schema 或全关)
app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

常见误区

  • 只关 Swagger 页面:/openapi.json 仍暴露接口结构与模型字段。
  • 文档路由与业务路由路径冲突:自定义路径时避免覆盖业务接口。

追问

  • 生产完全关闭文档有什么代价?答:外部无法自助查阅接口,内部联调需另开受保护环境。
  • 文档怎么加登录保护?答:文档路由走认证依赖,或在网关/反代层限制来源。

04.7.15.4-026 如何自定义 openapi() 函数修改生成的 schema?

一句话结论

子类化或重写 app.openapi():先调用默认生成逻辑拿到 schema dict,再按需增删改(移除内部字段、调整分组、补充响应码、注入通用头说明),缓存结果避免每次重新生成。也可在构造后通过覆盖 app.openapi 方法实现。

概念解释

  • 自定义适合跨端点统一处理:全局错误模型、内部标签清理、字段级隐藏。
  • schema 是普通 dict,按 OpenAPI 结构修改,改坏会导致 UI 报错。

原理流程

  1. 定义生成函数:调用 FastAPI.openapi 基类逻辑得到 schema。
  2. 遍历 paths/components.schemas 做定制。
  3. 结果缓存到实例属性,重复调用直接返回。
  4. 把函数挂到 app.openapi。

代码或图示

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = FastAPI.openapi(app)
    # 示例:补充全局 500 响应说明
    for path in schema["paths"].values():
        for op in path.values():
            op.setdefault("responses", {})["500"] = {
                "description": "服务器内部错误"
            }
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi

常见误区

  • 每次请求都重新生成 schema:浪费 CPU,应缓存。
  • 直接删除模型引用而不清理 $ref:文档出现悬空引用。

追问

  • 自定义后怎么验证 schema 合法?答:访问 /openapi.json 用 OpenAPI 校验器检查,Swagger UI 无报错。
  • 与 tags_metadata 相比适用场景?答:静态分组用 metadata;批量规则改造用自定义 openapi()。

04.7.15.4-027 tags_metadata 如何组织接口分组与描述?

一句话结论

tags_metadata 是标签元数据列表,为每个 tags 名称提供 name 与 description;路由装饰器用 tags=["商品"] 归属分组,文档按标签聚合排序,组描述展示在 Swagger/ReDoc 顶部。跨大模块的接口用标签比拆多应用更轻量。

概念解释

  • 标签可多层语义复用,但 OpenAPI 分组是扁平标签维度。
  • metadata 中未声明的标签仍会出现在文档,只是没有补充描述。

原理流程

  1. 构造应用时定义 tags_metadata 列表。
  2. 路由用 tags=[...] 标记归属。
  3. 生成 schema 时按标签聚合操作,附带描述。
  4. UI 按 metadata 顺序展示分组。

代码或图示

tags_metadata = [
    {"name": "商品", "description": "商品查询与维护接口"},
    {"name": "订单", "description": "下单、支付与履约相关接口"},
]
app = FastAPI(tags_metadata=tags_metadata)

@app.get("/items", tags=["商品"])
def list_items():
    ...

常见误区

  • 路由标签拼写与 metadata 不一致:分组描述丢失,接口散落在未分组区。
  • 标签过多过细:文档分组碎片化,建议按业务模块控制数量。

追问

  • 一个路由能挂多个标签吗?答:可以,tags 列表允许多标签,接口会在各分组出现。
  • 标签顺序怎么控制?答:按 tags_metadata 列表顺序展示。

04.7.15.4-028 路由的 summary、description、response_description 有什么区别?

一句话结论

summary 是接口短标题(列表展示),description 是详细说明(支持 Markdown),response_description 是成功响应的描述(默认 "Successful Response")。函数 docstring 也可作为描述来源;三者补充在路由装饰器上,文档可读性与签名类型信息分开维护。

概念解释

  • summary 缺失时文档用路径/方法作为标题。
  • response_description 只描述默认成功响应,其他状态码在 responses 中声明。

原理流程

  1. 路由装饰器填写标题与说明文字。
  2. 生成 schema 时映射到 Operation 的 summary/description/responses 描述。
  3. UI 在接口卡片展示标题、正文与成功响应说明。
  4. Markdown 描述在 Swagger/ReDoc 中渲染。

代码或图示

@app.post(
    "/items",
    summary="创建商品",
    description="根据请求体创建商品,库存不足时返回 409。",
    response_description="创建成功,返回商品详情",
)
def create_item(item: ItemIn):
    ...

常见误区

  • 把业务规则写进类型模型,文档却不说明:调用方不知道前置条件与错误分支。
  • description 与 docstring 重复维护:选定一处为准,避免内容漂移。

追问

  • 描述支持 Markdown 吗?答:支持,可含列表、代码块与强调。
  • 弃用接口怎么标注?答:路由参数 deprecated=True,文档标记为弃用。

04.7.15.4-029 Swagger UI 与 ReDoc 的差异与访问路径?

一句话结论

Swagger UI(默认 /docs)支持试发请求、表单填参与交互式调试;ReDoc(默认 /redoc)以文档目录排版为主,阅读体验好但交互调试能力弱。两者都消费同一份 /openapi.json,可按受众选择开启。

概念解释

  • Swagger UI 适合联调与接口自测;ReDoc 适合对外阅读型文档。
  • UI 静态资源由框架内置提供,可配置 CDN 或本地化部署。

原理流程

  1. 框架注册两个文档页面路由。
  2. 页面加载后请求 openapi_url 的 schema。
  3. Swagger 渲染可执行表单;ReDoc 渲染分组文档。
  4. 后端 schema 变更后页面刷新即反映。

代码或图示

/docs   → Swagger UI(交互式调试)
/redoc  → ReDoc(阅读型排版)
/openapi.json → 原始 schema

常见误区

  • 以为两个页面生成不同 schema:它们读取的是同一份 OpenAPI JSON。
  • 网络环境无法访问 CDN 时 UI 白屏:需本地化静态资源或配置可访问 CDN。

追问

  • 能只开其中一个吗?答:构造参数把另一个 URL 传 None。
  • 对外文档用哪个?答:公开只读文档常用 ReDoc;内部联调优先 Swagger UI。

04.7.15.4-030 include_in_schema=False 在什么场景使用?

一句话结论

路由装饰器参数 include_in_schema=False 让该端点不出现在 OpenAPI schema 与文档 UI 中,但接口仍可正常访问。适用于健康检查、内部回调、调试端点、临时运维接口等不想对外暴露结构的路由;隐藏不等于安全,敏感接口仍需鉴权。

概念解释

  • 隐藏的是文档呈现,不是接口访问控制。
  • 依赖与模型不被该端点引用后,也可能从 schema 组件中消失。

原理流程

  1. 路由标记 include_in_schema=False。
  2. 生成 schema 时跳过该操作条目。
  3. 文档不展示,但服务器仍匹配并执行该路由。
  4. 接口保护通过认证/网络策略另行实现。

代码或图示

@app.get("/health", include_in_schema=False)
def health():
    return {"status": "ok"}

常见误区

  • 把隐藏当安全措施:攻击者仍可探测路径,敏感接口必须做认证与限流。
  • 隐藏端点引用了内部模型:模型若被其他端点引用仍会出现在组件 schema 中。

追问

  • 怎么批量隐藏内部路由?答:在路由分组/APIRouter 上统一标记,或自定义 openapi() 过滤。
  • 隐藏后调试接口还能测吗?答:能用 HTTP 客户端直接调用,只是不出现在 UI 表单里。

04.7.15.4-031 openapi_examples 与请求/响应示例如何定制?

一句话结论

路由装饰器的 openapi_examples 为请求体提供多组示例(名称、摘要、值、外部文档);响应示例可在响应模型字段用 json_schema_extra,或在 responses 中声明 examples。示例直接展示在 Swagger UI 表单与 ReDoc 文档中,便于调用方理解字段含义与边界值。

概念解释

  • openapi_examples 对应 OpenAPI 的 examples 字段,与旧版单值 example 并存。
  • 模型级示例随 Pydantic 字段配置进入组件 schema。

原理流程

  1. 在路由参数或模型字段上填写示例值。
  2. 生成 schema 时写入请求/响应的 example(s)。
  3. UI 渲染示例下拉与预填表单。
  4. 示例值不参与运行时校验,仅作文档展示。

代码或图示

@app.post("/items", openapi_examples={
    "normal": {
        "summary": "普通商品",
        "value": {"name": "水杯", "price": 19.9},
    },
    "premium": {
        "summary": "高端商品",
        "value": {"name": "陶瓷杯", "price": 199.0},
    },
})
def create(item: ItemIn):
    ...

常见误区

  • 把示例当校验规则:示例值错误不会被服务端拦截,需另靠模型约束。
  • 示例里放真实敏感数据:文档外泄即造成信息泄露。

追问

  • 模型字段怎么写示例?答:Pydantic v2 用 Field(..., json_schema_extra={"example": ...})。
  • 响应示例在哪里声明?答:responses 字典中对应状态码条目内的 examples/example。

04.7.15.4-032 responses 参数如何声明多状态码响应模型?

一句话结论

路由 responses 参数是字典:键为 HTTP 状态码,值含 model(响应模型)、description、examples 等;用于补充 response_model 之外的错误/特殊响应(400、401、403、404、409、500),让文档完整覆盖成功与失败分支。

概念解释

  • response_model 描述默认成功响应;responses 补充其他状态码结构。
  • 同一状态码的模型会进入 OpenAPI 组件复用。

原理流程

  1. 列出端点可能返回的全部状态码。
  2. 为每个错误状态码指定模型与描述。
  3. 生成 schema 时合并成功响应与补充响应。
  4. 文档展示各分支结构,客户端按码处理。

代码或图示

@app.post(
    "/items",
    response_model=ItemOut,
    responses={
        404: {"model": ErrorOut, "description": "商品不存在"},
        409: {"model": ErrorOut, "description": "库存冲突"},
        500: {"description": "服务器内部错误"},
    },
)
def create(item: ItemIn):
    ...

常见误区

  • 只声明 200 响应:文档看不到错误分支,调用方靠猜处理异常。
  • 错误模型与实际处理器返回结构不一致:文档与运行行为脱节。

追问

  • 全局错误模型要不要每个路由重复写?答:可在自定义 openapi() 中按规则批量补到所有操作。
  • 状态码能用字符串键吗?答:OpenAPI 状态码为字符串,框架参数接受数字键并转换。

04.7.15.4-033 安全方案如何写进 OpenAPI 文档?

一句话结论

安全方案对象(OAuth2PasswordBearer、HTTPBearer、APIKeyHeader 等)被依赖引用后,自动在 schema 的 components.securitySchemes 生成对应定义;路由级 security 条目说明该操作使用哪个方案。文档 UI 据此渲染授权按钮与凭证填写框。

概念解释

  • 方案类型映射:HTTP Bearer → http/bearer;OAuth2 password → oauth2 flow;API Key → apiKey。
  • 未被任何依赖引用的方案不会进入 schema。

原理流程

  1. 实例化安全方案并在依赖中 Depends 引用。
  2. 生成 schema 时收集方案元数据到 securitySchemes。
  3. 路由操作追加 security 引用,绑定方案与 scope。
  4. Swagger 授权后把凭证加入后续请求头。

代码或图示

# schema 中大致生成:
# "securitySchemes": {
#   "OAuth2PasswordBearer": {
#     "type": "oauth2",
#     "flows": {"password": {"tokenUrl": "auth/login"}}
#   }
# }

常见误区

  • 方案对象声明了但依赖里没引用:文档不出现该方案。
  • 多套凭证体系混用未区分:文档出现多个相似方案,调用方选错。

追问

  • 怎么在文档里隐藏安全方案?答:自定义 openapi() 移除对应 securitySchemes 与路由 security。
  • 方案 scheme_name 有什么用?答:作为 schema 中该方案的键名,便于多方案区分。

04.7.15.4-034 scope 在 OpenAPI 文档中如何组合展示?

一句话结论

方案实例化时声明 scopes,路由通过 Security(dep, scopes=[...]) 标记所需范围;OpenAPI 在方案 flow 下列出 scope 描述,并在操作 security 条目中引用所需 scope。Swagger 授权界面按方案展示可勾选/已授予范围。

概念解释

  • scope 挂在安全方案下,属于 OAuth2 流程定义的一部分。
  • 操作级 security 可覆盖/补充方案默认 scope。

原理流程

  1. 方案定义可用 scope 与中文描述。
  2. 路由声明要求的 scope 列表。
  3. schema 合并方案 scope 与操作所需 scope。
  4. UI 授权时展示范围,请求携带对应 token。

代码或图示

oauth2 = OAuth2PasswordBearer(tokenUrl="login", scopes={
    "read:items": "读取商品",
    "write:items": "写入商品",
})

@app.get("/items", dependencies=[Security(oauth2, scopes=["read:items"])])
def list_items():
    ...

常见误区

  • 方案声明了 scope 但路由不标所需范围:文档看不出接口最小权限。
  • scope 命名不一致(冒号、大小写):文档分组与校验对不上。

追问

  • 多个方案在同一接口可以组合吗?答:OpenAPI 支持 security 条目内多方案组合(AND/OR 语义按规范解释),FastAPI 依赖层再做实际校验。
  • scope 描述在哪写?答:方案构造参数的 scopes 字典,键为 scope 名,值为描述。

04.7.15.4-035 依赖注入做权限校验有哪些最佳实践?

一句话结论

把“认证”与“授权”拆成两层依赖:认证依赖返回当前用户,授权依赖接收用户并校验角色/scope/资源归属;权限规则集中在依赖或策略类,不在每个端点复制判断。路由通过 Depends/Security 组合复用,失败抛 401/403,异常格式统一。

概念解释

  • 认证(authentication):你是谁;授权(authorization):你能做什么。
  • 可复用依赖让权限变更集中修改,避免遗漏端点。

原理流程

  1. get_current_user 完成凭证校验与用户加载。
  2. 权限依赖(如 require_roles("admin"))接收用户并判断。
  3. 不满足抛 403;未认证由认证依赖抛 401。
  4. 端点只接收已授权用户/资源对象。

代码或图示

def require_admin(user: User = Depends(get_current_user)) -> User:
    if "admin" not in user.roles:
        raise HTTPException(403, "需要管理员权限")
    return user

@app.delete("/users/{uid}")
def delete_user(uid: str, admin: User = Depends(require_admin)):
    ...

常见误区

  • 端点内直接读 token 判权限:逻辑散落,难以审计与复用。
  • 只做角色粗粒度判断,不校验资源归属:越权访问他人数据。

追问

  • 权限校验放中间件还是依赖?答:路由级、参数相关的授权放依赖;全局粗粒度拦截可放中间件,资源归属必须在依赖/服务层。
  • 策略规则怎么集中管理?答:策略类/权限表按角色与资源映射,依赖调用策略判定。

04.7.15.4-036 角色与权限校验依赖怎么分层复用?

一句话结论

按层级沉淀:基础认证依赖 → 角色校验工厂(按角色名生成依赖)→ 资源级权限依赖(结合路径参数查归属)。工厂闭包复用同一套判定逻辑,APIRouter 级别批量挂载一组依赖,路由只声明所需角色。

概念解释

  • 依赖工厂返回新的依赖函数,闭包保存角色/权限参数。
  • 路由组统一挂依赖,组内端点无需重复书写。

原理流程

  1. 定义认证依赖返回用户对象。
  2. 工厂函数 has_role(role) 返回校验依赖。
  3. 资源依赖读取路径参数,查资源归属后比对用户。
  4. 路由器或端点按需要注入对应依赖。

代码或图示

def has_role(role: str):
    def checker(user: User = Depends(get_current_user)) -> User:
        if role not in user.roles:
            raise HTTPException(403)
        return user
    return checker

admin_router = APIRouter(dependencies=[Depends(has_role("admin"))])

常见误区

  • 每个端点手写一遍角色判断:规则变更要改多处,易漏。
  • 权限依赖返回布尔值而不是用户对象:下游拿不到身份,还得重新取。

追问

  • 多角色 OR 校验怎么写?答:工厂接收角色列表,依赖内判断任一命中;AND 用多个依赖串联。
  • 路由器依赖与端点依赖优先级?答:路由器依赖先执行,再到端点依赖,授权可分层拦截。

04.7.15.4-037 多租户与资源归属校验怎么做?

一句话结论

资源归属校验在拿到路径参数/资源对象后进行:查询时带上租户 ID 与用户条件,返回前复核资源属于当前用户或其租户;不能只靠前端传 ID。租户上下文从认证信息派生,不信任请求体中的租户字段。

概念解释

  • 越权分水平越权(访问他人同层数据)与垂直越权(访问高权限功能)。
  • 数据层查询条件带租户/用户隔离,是归属校验的最后一道防线。

原理流程

  1. 认证依赖解析出用户 ID 与租户 ID。
  2. 服务层按 resource_id + tenant_id/user_id 查询。
  3. 未查到或归属不符抛 404/403。
  4. 响应模型不跨租户暴露敏感字段。

代码或图示

@app.get("/orders/{oid}")
async def order(oid: str, user: User = Depends(get_current_user)):
    record = await order_repo.get(oid, tenant_id=user.tenant_id)
    if record is None:
        raise HTTPException(404, "订单不存在")
    return record

常见误区

  • 按主键直接查询后只判断登录态:水平越权拿到他人订单。
  • 信任请求体里的 tenant_id:可被篡改,必须从认证上下文派生。

追问

  • 管理员跨租户查看怎么放行?答:策略判断角色为管理员时放宽归属条件,普通用户严格隔离。
  • 列表接口怎么做隔离?答:查询默认追加租户/用户过滤条件,不提供“全量”入口。

04.7.15.4-038 认证依赖与业务依赖如何组合(AND 关系)?

一句话结论

多个 Depends 按声明顺序依次执行,全部通过才进入端点,构成 AND 关系;认证依赖先返回用户,授权/资源依赖再基于用户校验。依赖可被路由器、端点、子依赖多层嵌套,前序依赖的结果注入后序依赖参数。

概念解释

  • 依赖图是 DAG:框架解析共享依赖并按拓扑顺序执行。
  • 同一依赖在链路中默认结果缓存(同一次请求内复用)。

原理流程

  1. 解析端点参数与依赖树。
  2. 先执行认证依赖,得到用户对象。
  3. 授权、资源依赖注入用户与路径参数继续校验。
  4. 任一依赖抛错即中断,不进入端点函数体。

代码或图示

@app.post("/orders/{oid}/approve")
def approve(
    oid: str,
    user: User = Depends(get_current_user),
    order: Order = Depends(get_order_by_path),  # 依赖内校验归属
    _: User = Depends(has_role("manager")),
):
    ...

常见误区

  • 以为依赖是 OR 关系:多个依赖全部必须通过,不会任一命中即放行。
  • 后序依赖重新查用户:复用前序注入结果即可,避免重复解析 token。

追问

  • 依赖执行失败顺序怎么保证?答:按依赖图拓扑顺序,认证类依赖应排最前。
  • 同一依赖在一次请求内会执行几次?答:默认缓存复用;需要每次重算可关闭缓存(按框架版本核对参数)。

04.7.15.4-039 令牌在客户端存储有哪些 XSS/CSRF 风险?

一句话结论

Bearer token 存 localStorage/sessionStorage 易被 XSS 脚本读取;存内存可降低持久化泄露但刷新页面丢失。HttpOnly Cookie 防 JS 读取,但要防 CSRF(SameSite、CSRF Token)。没有绝对安全的存储,需结合 XSS 防护、CSP、短令牌与吊销机制。

概念解释

  • XSS 偷取持久化令牌;CSRF 利用浏览器自动携带 Cookie 发起伪造请求。
  • 风险与前端形态(SPA、服务端渲染、移动端)相关。

原理流程

  1. 登录后按架构选择令牌存储位置。
  2. 前端做好输入输出转义与 CSP,降低 XSS 面。
  3. Cookie 方案配置 SameSite、HttpOnly、Secure 与 CSRF 防护。
  4. 令牌短寿命 + 可吊销,降低泄露后影响窗口。

代码或图示

localStorage:JS 可读,XSS 即泄露
内存:刷新丢失,XSS 当次可读取
HttpOnly Cookie:JS 不可读,需防 CSRF

常见误区

  • 以为存 Cookie 就免做 CSRF:自动携带特性反而引入跨站伪造风险。
  • 只靠前端藏 token:后端必须按短寿命、吊销、限流做纵深防御。

追问

  • 移动端原生应用存哪里?答:系统安全存储(Keychain/Keystore),不写普通明文配置。
  • XSS 防护包括哪些?答:输出转义、CSP、富文本清洗、依赖漏洞更新、避免内联脚本。

一句话结论

Bearer Token 便于 SPA/移动端携带与跨域调用,但存储风险自担;Cookie 会话由浏览器管理、HttpOnly 防脚本读取,但需处理 CSRF、SameSite 与跨域配置。同站前后端推荐 Cookie + CSRF 防护;跨域 API/多端客户端常用 Bearer + 短令牌。

概念解释

  • Cookie 随请求自动携带;Bearer 由前端手动放入 Authorization 头。
  • 会话型服务端可查可吊销;JWT 无状态但吊销依赖黑名单。

原理流程

  1. 按部署形态(同站/跨域/多端)选择凭证传递方式。
  2. Cookie 方案配置安全属性与 CSRF Token。
  3. Bearer 方案在响应中返回 token,前端按安全位置保存。
  4. 服务端校验逻辑一致,差别在凭证来源与防护重点。

代码或图示

response.set_cookie(
    "session", token, httponly=True, secure=True,
    samesite="Lax", max_age=3600,
)

常见误区

  • 跨站场景用 SameSite=None 却不加 CSRF 防护:跨站伪造请求风险升高。
  • Bearer token 长期有效且不支持吊销:泄露后只能等过期。

追问

  • 混合架构怎么选?答:主站 Cookie 会话,开放 API/第三方客户端用 Bearer,两套鉴权依赖并存。
  • Cookie 跨域读不到怎么办?答:需 SameSite=None; Secure 且后端 CORS 允许凭证,配合前端携带 credentials。

04.7.15.4-041 接口速率限制与认证失败计数怎么做?

一句话结论

按主体(IP、用户 ID、API Key)对登录、鉴权与敏感接口做速率限制:失败次数累计,超阈值临时锁定或要求验证码;计数与配额存 Redis 等共享存储,区分单机与分布式限流。认证失败计数用于防暴力破解,普通接口限流用于保护容量。

概念解释

  • 登录接口是凭证填充(credential stuffing)入口,限流与审计优先。
  • 锁定策略要防“故意锁死他人账号”:按 IP 与账号双维度限制。

原理流程

  1. 入口识别主体维度(IP/账号/key)。
  2. 读取窗口内失败计数与配额。
  3. 超限返回 429 或锁定提示;成功后清零失败计数。
  4. 记录失败事件用于审计与告警。

代码或图示

async def check_login_rate(ip: str, username: str):
    key = f"login_fail:{ip}:{username}"
    count = await redis.incr(key)
    await redis.expire(key, 300)
    if count > 5:
        raise HTTPException(429, "尝试过于频繁,请稍后再试")

常见误区

  • 只按账号限流:攻击者换账号遍历;只按 IP 限流: NAT 下误伤大量用户。
  • 失败锁定不区分来源:被用于对目标账号发起拒绝服务式锁定。

追问

  • 429 与 403 区别?答:429 是速率超限可重试;403 是权限不足不可重试。
  • 分布式计数器怎么保证一致?答:Redis 原子 incr + TTL,配合 Lua 脚本处理复合判定。

04.7.15.4-042 JWT 签名密钥如何管理与轮换?

一句话结论

签名密钥从环境变量/密钥管理服务读取,不写进源码与仓库;按环境分离密钥(开发/测试/生产),支持多密钥并存轮换(kid 头标记密钥版本,验签时按 kid 选密钥)。定期轮换密钥,泄露时立即作废旧密钥并强制刷新令牌。

概念解释

  • 对称密钥(HS256)签发验签同一份;非对称(RS256)私钥签发、公钥分发验签。
  • 密钥进入日志、错误信息或文档都是泄露面。

原理流程

  1. 启动时从配置/密钥服务加载当前私钥与可选历史公钥。
  2. 签发时写入 kid 标识密钥版本。
  3. 验签按 kid 选择对应密钥,算法白名单校验。
  4. 轮换期新旧密钥并存,旧令牌平滑过渡后下线旧密钥。

代码或图示

ALG = "RS256"
# 签发:私钥;验签:公钥集合按 kid 选取
headers = {"kid": "2026-11"}
token = jwt.encode(payload, private_key, algorithm=ALG, headers=headers)

常见误区

  • 把默认示例密钥带进生产:任何拿到源码的人都能伪造令牌。
  • 轮换时直接替换密钥:旧签名令牌全部失效,应并存过渡。

追问

  • 密钥轮换后旧 token 怎么办?答:过渡期保留旧公钥验签,过期后移除;必要时强制重新登录。
  • 私钥泄露如何应急?答:立即轮换密钥、吊销现有令牌、审计异常签发与访问记录。

04.7.15.4-043 审计日志应记录哪些认证授权事件?

一句话结论

关键事件:登录成功/失败、令牌刷新、登出、权限变更、401/403 触发、敏感操作、密钥/配置变更;记录主体标识、来源 IP、时间、User-Agent、结果与请求 ID,不记录密码、完整令牌与敏感参数。日志集中存储并接入告警,异常批量失败触发排查。

概念解释

  • 审计日志面向事后追责与安全告警,与业务访问日志粒度不同。
  • 日志本身要防篡改与越权读取。

原理流程

  1. 认证/授权依赖在关键节点写审计事件。
  2. 字段填充主体、来源、结果与关联 ID。
  3. 敏感字段脱敏后落库/日志系统。
  4. 规则匹配异常模式(批量失败、异地登录、越权尝试)并告警。

代码或图示

audit.log({
    "event": "login_failed",
    "username": form.username,
    "ip": request.client.host,
    "result": "bad_password",
    "request_id": rid,
})

常见误区

  • 日志里打完整 token 或密码:日志泄露即凭证泄露。
  • 只记成功不记失败:暴力破解与越权尝试无法追溯。

追问

  • 审计日志保留多久?答:按合规要求设定周期,访问与安全事件分级留存。
  • 日志里能记手机号等个人信息吗?答:按隐私要求脱敏或最小化收集。

04.7.15.4-044 OAuth2 授权码流程在 FastAPI 中怎么对接?

一句话结论

授权码流程用于对接第三方身份提供方:前端/服务端跳转授权页 → 用户同意后回调带 code → 后端用 code 换 access/refresh token → 校验用户并建立本地会话。FastAPI 侧实现回调路由、令牌交换与用户映射;对外授权地址、token 端点由身份提供方配置。

概念解释

  • 授权码流程适合有后端的 Web 应用,客户端密钥不暴露给浏览器。
  • 与密码模式区别:用户不把账号密码交给本应用,而是在 IdP 登录。

原理流程

  1. 重定向到 IdP 授权地址,携带 client_id、redirect_uri、state、scope。
  2. 用户登录授权,IdP 回调本地路由并附 code。
  3. 后端用 code + 客户端密钥向 token 端点换令牌。
  4. 取用户信息,绑定/创建本地用户,签发本地会话令牌。

代码或图示

@app.get("/auth/callback")
async def oauth_callback(code: str, state: str, request: Request):
    verify_state(state)
    token = await idp_client.exchange_code(code, request)
    profile = await idp_client.userinfo(token)
    user = await upsert_user(profile)
    return issue_local_session(user)

常见误区

  • 后端直接把 IdP 令牌当本地授权依据:应映射本地用户与权限,避免外部身份体系耦合。
  • 回调不校验 state:跨站请求伪造(CSRF)可绑定他人账号。

追问

  • 客户端密钥放哪里?答:服务端环境变量/密钥服务,不下发到前端。
  • PKCE 什么时候用?答:SPA/移动端等无法保密客户端密钥的场景,启用 code challenge 校验。

04.7.15.4-045 第三方登录回调的 state 校验怎么做?

一句话结论

跳转授权前生成随机 state 存入服务端会话/短时缓存,回调时比对返回的 state,一致才继续;state 同时绑定 CSRF 防护与回调上下文(来源页面、权限范围)。过期或不匹配直接拒绝,防止授权码被跨站劫持绑定。

概念解释

  • state 是一次性、不可预测的随机值,短 TTL。
  • 回调还应校验 redirect_uri 与注册地址一致。

原理流程

  1. 生成随机 state,关联本地会话上下文并缓存。
  2. 授权 URL 携带 state。
  3. 回调取回 state,查缓存比对并消费(一次性)。
  4. 校验通过再换令牌;失败记录审计并拒绝。

代码或图示

state = secrets.token_urlsafe(24)
await redis.setex(f"oauth_state:{state}", 300, user_session_id)

@app.get("/auth/callback")
async def callback(code: str, state: str):
    session_id = await redis.getdel(f"oauth_state:{state}")
    if not session_id:
        raise HTTPException(400, "state 无效或已过期")
    ...

常见误区

  • state 用可预测值或固定字符串:失去防伪造意义。
  • 回调后不删除 state:重放同一回调可能再次绑定。

追问

  • state 过期时间设多长?答:与授权等待窗口匹配,通常数分钟,短 TTL 降低重放风险。
  • 除了 state 还要校验什么?答:redirect_uri 白名单、IdP 签发的令牌声明与用户信息归属。

04.7.15.4-046 权限不足返回 403 与未认证 401 如何区分?

一句话结论

401 Unauthorized 表示缺少或无效凭证(未登录/令牌过期伪造),应带 WWW-Authenticate 提示认证方式;403 Forbidden 表示已认证但权限不足。先认证后授权:无凭证抛 401,有凭证但越权抛 403,两者不可混用。

概念解释

  • 401 触发重新认证流程;403 不会引导登录,前端按无权限处理。
  • 错误响应体不应泄露资源是否存在(归属不明时可统一 404/403 策略)。

原理流程

  1. 认证依赖解析凭证,缺失/无效抛 401。
  2. 用户加载成功后进入授权校验。
  3. 角色/scope/归属不足抛 403。
  4. 响应经统一异常处理器格式化。

代码或图示

async def get_current_user(token: str | None = Depends(oauth2_scheme)):
    if not token:
        raise HTTPException(401, "未登录",
                            headers={"WWW-Authenticate": "Bearer"})
    ...

def require_admin(user: User = Depends(get_current_user)):
    if "admin" not in user.roles:
        raise HTTPException(403, "无管理员权限")
    return user

常见误区

  • 未登录也返回 403:客户端无法区分该跳转登录还是提示无权限。
  • 403 响应体列出“缺少哪些权限”:帮助攻击者枚举权限位,按最小信息返回。

追问

  • 401 一定要带 WWW-Authenticate 吗?答:Bearer 方案建议携带,便于客户端与调试工具识别认证方式。
  • 资源不存在与无权访问怎么响应?答:对外可统一 404 避免探测,内部日志区分原因。

04.7.15.4-047 文档中如何隐藏敏感字段与内部模型?

一句话结论

用独立的输入/输出模型剥离内部字段(哈希、内部 ID、标记位);模型字段可标记 exclude 或不放入响应模型;内部服务模型不直接作为 response_model。需要在 schema 中移除字段时,可结合模型继承与自定义 openapi() 过滤。

概念解释

  • 数据库模型(ORM/内部实体)与 API 模型分层是隐藏敏感字段的基础。
  • 文档可见范围 = 被路由响应模型与请求模型引用的字段集合。

原理流程

  1. 定义 XxxIn/XxxOut 模型,只暴露对外字段。
  2. ORM 实体映射到 Out 模型,敏感字段不参与序列化。
  3. 响应类型标注为 Out 模型。
  4. 必要时自定义 openapi() 删除组件中遗留的内部字段。

代码或图示

class UserOut(BaseModel):
    id: int
    username: str
    # hashed_password、internal_status 不出现

@app.get("/users/{uid}", response_model=UserOut)
def get_user(uid: int):
    return user_repo.get(uid)

常见误区

  • 直接返回 ORM 对象:未排除的内部字段全部进入响应与文档。
  • 以为 include_in_schema=False 能隐藏字段:它作用于端点,字段隐藏靠模型分层。

追问

  • 字段名在文档里能改名吗?答:通过模型字段别名序列化,schema 使用别名展示。
  • 嵌套模型敏感字段怎么排除?答:嵌套层级都使用对外 Out 模型,不嵌套内部实体。

04.7.15.4-048 响应模型与 OpenAPI schema 是什么关系?

一句话结论

response_model 声明的 Pydantic 模型被框架转换为 JSON Schema,挂到 OpenAPI 操作的响应内容下;它同时约束运行时序列化(过滤字段、校验输出)和文档展示。未声明响应模型时,框架按返回值推断,文档结构可能与实际输出脱节。

概念解释

  • 响应模型双重作用:运行时过滤/校验 + 文档生成。
  • 模型字段类型、必填、约束直接成为 schema 规则。

原理流程

  1. 路由标注 response_model=ItemOut。
  2. 运行时:返回值经模型校验与字段过滤后序列化。
  3. 生成文档:模型转 JSON Schema 写入响应定义。
  4. 客户端按 schema 解析响应。

代码或图示

@app.get("/items/{iid}", response_model=ItemOut)
def item(iid: int):
    return Item(name="杯", price=19.9)

常见误区

  • 端点返回裸 dict 且不声明模型:文档只显示通用对象,字段约束缺失。
  • 响应模型与实际返回字段不一致:运行时被过滤掉文档里出现的字段,前后端联调困惑。

追问

  • response_model 会修改返回对象吗?答:按模型字段过滤并校验输出,多余字段被排除。
  • 列表响应怎么声明模型?答:response_model=list[ItemOut] 或 list[ItemOut] 类型标注。

04.7.15.4-049 Pydantic 模型如何影响生成的 schema?

一句话结论

字段类型成为 schema 类型(string/number/boolean/array/object),Field 约束(min_length、max_length、ge/le、pattern、enum)成为 schema 约束;必填/可选决定 required 列表,默认值写入 schema 示例。Pydantic v2 用 model_config 与 field_validator,约束同时作用于校验与文档。

概念解释

  • 模型既是运行时校验器,也是 schema 来源,两处规则天然一致。
  • 嵌套模型生成嵌套 $ref 组件定义。

原理流程

  1. 定义模型字段类型与 Field 约束。
  2. 框架调用模型的 JSON Schema 生成能力。
  3. 约束、必填、示例写入 OpenAPI 组件。
  4. 文档展示校验规则,客户端据此生成表单与类型。

代码或图示

from pydantic import BaseModel, Field

class ItemIn(BaseModel):
    name: str = Field(min_length=2, max_length=50)
    price: float = Field(gt=0, le=100000)
    tags: list[str] = Field(default_factory=list)

常见误区

  • 只在数据库层做约束,API 模型不声明:文档与前端拿不到校验规则,错误推迟到入库。
  • 用 Any/dict 承载请求体:schema 退化为自由对象,失去类型保护与文档价值。

追问

  • 枚举类型在文档里怎么展示?答:Literal/Enum 字段生成 enum 可选值列表。
  • 模型别名影响 schema 吗?答:序列化别名成为对外字段名,schema 按别名生成。

04.7.15.4-050 多版本 API 与文档分组怎么组织?

一句话结论

按路径前缀分版本(/v1/items、/v2/items),用 APIRouter 分组并挂不同标签;文档可通过 tags 分组展示各版本,或为不同版本挂独立子应用/独立文档入口。版本变更要保持旧版兼容,废弃接口在文档标记 deprecated 并给出迁移说明。

概念解释

  • 版本策略:URL 前缀、请求头、内容协商;FastAPI 路由层最直接支持前缀方案。
  • 多版本共享模型时注意字段演进不要破坏旧契约。

原理流程

  1. 按版本创建 APIRouter,设置前缀与标签。
  2. 路由挂载到主应用对应路径。
  3. OpenAPI 按标签聚合各版本接口。
  4. 旧版本接口标记弃用,保留过渡期后下线。

代码或图示

v1 = APIRouter(prefix="/v1", tags=["v1"])
v2 = APIRouter(prefix="/v2", tags=["v2"])

app.include_router(v1)
app.include_router(v2)

常见误区

  • 同一模型跨版本直接复用:新版加必填字段会破坏旧版请求契约。
  • 文档不标弃用:调用方继续依赖即将下线的接口。

追问

  • 能给每个版本独立 OpenAPI JSON 吗?答:可挂子应用分别配置 openapi_url,或自定义 openapi() 按版本过滤 paths。
  • 版本废弃流程是什么?答:文档标注 → 通知调用方 → 兼容期 → 下线并监控残留调用。

04.7.15.4-051 测试/生产环境关闭文档要考虑什么?

一句话结论

生产关闭文档要同时处理 docs_url、redoc_url、openapi_url,避免 schema JSON 单独暴露;内部环境可用认证依赖或网络 ACL 保护文档,而不是简单依赖页面隐藏。关闭前确认联调渠道,保留最小内部可见性。

概念解释

  • 文档泄露接口结构、模型字段与内部路径,是信息收集入口。
  • 环境差异通过配置注入,不在代码里硬编码开关。

原理流程

  1. 按环境配置文档开关与路径。
  2. 生产关闭三个文档入口,或加认证/来源限制。
  3. 内部联调通过受保护环境访问文档。
  4. 上线前检查 /openapi.json 不可被外部访问。

代码或图示

docs_enabled = settings.env != "prod"
app = FastAPI(
    docs_url="/docs" if docs_enabled else None,
    redoc_url="/redoc" if docs_enabled else None,
    openapi_url="/openapi.json" if docs_enabled else None,
)

常见误区

  • 只关 Swagger 页面:/openapi.json 仍可直接下载完整 schema。
  • 文档入口与业务路由共用无保护内网:横向移动时接口结构直接暴露。

追问

  • 外部合作方需要文档怎么办?答:发布裁剪后的公开文档(ReDoc 静态导出/门户),不暴露内部 schema。
  • 怎么验证文档已关闭?答:外网访问三个路径均 404/401,扫描确认无残留。

04.7.15.4-052 认证中间件与认证依赖怎么选?

一句话结论

全局粗粒度拦截(所有请求必须带凭证、统一解析 token 放上下文)适合中间件;与路由参数、资源归属、角色 scope 相关的授权适合依赖。中间件做前置过滤,依赖做细粒度判定;两者可叠加,但不要在中间件里重复实现资源级权限。

概念解释

  • 中间件在路由匹配前执行,拿不到路径参数与路由声明。
  • 依赖能访问参数、模型与注入上下文,适合业务授权。

原理流程

  1. 中间件解析全局凭证,缺失则短路 401。
  2. 请求进入路由,认证依赖加载用户。
  3. 授权依赖结合参数校验角色/归属。
  4. 端点执行已授权业务。

代码或图示

# 中间件:全局凭证存在性检查
class TokenGate:
    def __init__(self, app):
        self.app = app
    async def __call__(self, scope, receive, send):
        if scope["type"] == "http" and not has_token(scope):
            await JSONResponse({"detail": "unauthorized"}, 401)(scope, receive, send)
            return
        await self.app(scope, receive, send)

常见误区

  • 在中间件里查库判角色:拿不到路径参数,且每请求重复业务逻辑。
  • 完全不用中间件,所有公开/私有接口靠依赖逐个挂:遗漏风险高。

追问

  • 中间件解析的用户怎么传给依赖?答:写入 scope 或上下文变量,依赖读取;注意类型与校验。
  • 静态/健康检查怎么放行?答:中间件按路径白名单跳过认证。

04.7.15.4-053 JWT 算法 none 与算法混淆攻击怎么防?

一句话结论

验签必须固定算法白名单(algorithms=["HS256"]),不接受 token 头部声明的算法;拒绝 alg: none 的未签名令牌;对称与非对称密钥分离,避免 RS256 公钥被当作 HS256 密钥使用的混淆。解码库在配置白名单后才校验签名。

概念解释

  • 算法混淆:攻击者把 RS256 令牌改为 HS256,用公开公钥当 HMAC 密钥签名伪造。
  • none 算法早期规范允许无签名,实现必须显式拒绝。

原理流程

  1. 签发时确定算法与密钥类型。
  2. 验签传入固定 algorithms 白名单与对应密钥。
  3. 库按白名单校验签名,头部算法不在列表即拒绝。
  4. 检查 alg 不为 none,必要时校验 kid 与密钥匹配。

代码或图示

# 安全:固定算法白名单
payload = jwt.decode(token, PUBLIC_KEY, algorithms=["RS256"])

# 危险:不限制算法,信任头部 alg
# jwt.decode(token, key)

常见误区

  • 用同一个变量同时放公钥与对称密钥:混淆攻击面扩大。
  • 只校验 exp 不验签:任何人可伪造声明。

追问

  • 怎么确认库拒绝 none 算法?答:构造 alg=none 令牌传入白名单解码,验证被拒。
  • 多算法共存怎么办?答:按 kid 映射密钥类型与允许算法,逐案配置白名单。

04.7.15.4-054 刷新令牌轮换与重放检测怎么做?

一句话结论

每次刷新签发新的 refresh token 并作废旧 token(轮换);服务端记录当前有效刷新令牌标识或版本,重放已作废 token 即判定泄露,吊销该用户全部会话。轮换链断裂/重复使用旧令牌触发安全告警。

概念解释

  • 轮换缩小泄露令牌可用窗口;重放检测发现令牌被窃取后重复使用。
  • 刷新令牌绑定设备/客户端信息,异地异客户端使用标记可疑。

原理流程

  1. 登录签发 refresh,记录其 jti 与用户/设备绑定。
  2. 刷新时校验 jti 有效,签发新 refresh,旧 jti 作废。
  3. 若收到已作废 jti:判定重放,吊销该用户所有令牌并告警。
  4. 绑定信息(设备、IP 段)变化时要求二次验证。

代码或图示

async def rotate_refresh(old_jti: str, user_id: str):
    current = await redis.get(f"refresh:{user_id}")
    if current != old_jti:
        await revoke_all(user_id)
        raise HTTPException(401, "令牌已失效,请重新登录")
    new_jti = secrets.token_urlsafe(24)
    await redis.setex(f"refresh:{user_id}", REFRESH_TTL, new_jti)
    return new_jti

常见误区

  • refresh token 永久不轮换:泄露后长期可用。
  • 只比对新 token 不记录旧链:无法识别旧令牌重放。

追问

  • 刷新接口也要限流吗?答:要,按用户与 IP 限制刷新频率,防止批量探测。
  • 重放检测误报怎么办?答:区分网络重试与异常来源,结合设备信息与频度判断。

04.7.15.4-055 凭证填充与撞库攻击怎么防护?

一句话结论

防护组合:登录限流与失败锁定、泄露密码库校验(拒绝已泄露口令)、异常检测(异地、多账号同 IP、高频尝试)、验证码/二次验证、设备指纹与告警。不向攻击者区分账号是否存在,统一错误响应;接入风控信号拦截批量尝试。

概念解释

  • 凭证填充用其他站点泄露的用户名密码组合批量尝试;撞库针对同一用户密码猜测。
  • 攻击多来自代理池/NAT,单 IP 阈值不够,需多维度信号。

原理流程

  1. 登录入口记录失败次数、来源与账号维度。
  2. 超阈值触发验证码/临时锁定/二次验证。
  3. 检测批量模式:同 IP 多账号、同账号多来源、高频失败。
  4. 可疑会话强制重认证,安全事件入审计并告警。

代码或图示

# 多维度计数示例
await redis.incr(f"fail:ip:{ip}")
await redis.incr(f"fail:user:{username}")
# 任一维度超阈值 → 验证码/锁定/风控拦截

常见误区

  • 只靠密码复杂度:用户复用泄露密码,复杂度高也会被撞中。
  • 锁定只按账号:攻击者轮换账号绕过;只按 IP:NAT 误伤。

追问

  • 怎么判断一批尝试是撞库?答:失败率高、密码分布集中、来源分散、账号集合大。
  • 二次验证(2FA)在防护中的位置?答:作为凭证泄露后的第二道防线,敏感账号强制开启。

04.7.15.4-056 密码策略与强度校验怎么定?

一句话结论

策略包含最小长度、字符类别要求、弱口令黑名单、禁止与账号信息雷同、定期更换(按业务风险);注册与改密时校验强度,校验结果给出明确字段级提示。服务端强制策略,前端提示仅为体验补充。

概念解释

  • 强度平衡安全性与可记忆性:过长过复杂导致用户写便利贴或复用。
  • 泄露密码库校验比静态规则更能拦截真实弱口令。

原理流程

  1. 设定长度与类别规则、弱口令/泄露密码名单。
  2. 注册/改密接口在哈希前校验密码。
  3. 不满足返回字段级错误,说明缺口。
  4. 校验通过后慢哈希入库。

代码或图示

import re

def validate_password(pw: str) -> list[str]:
    issues = []
    if len(pw) < 10:
        issues.append("长度不少于 10 位")
    if not re.search(r"[A-Z]", pw) or not re.search(r"[0-9]", pw):
        issues.append("需含大写字母与数字")
    if pw.lower() in weak_passwords:
        issues.append("密码过于常见")
    return issues

常见误区

  • 强制每类字符都有且定期换密码:用户产生可预测变形(Password123! 递增)。
  • 只在前端校验:绕过前端直接调接口可提交弱口令。

追问

  • 密码最大长度有限制吗?答:受哈希算法(bcrypt 72 字节)与存储长度约束,超长先预哈希或拒绝。
  • 泄露密码库怎么接入?答:使用离线/专用校验服务,比对摘要而不是明文传输密码。

04.7.15.4-057 会话固定与登出失效怎么处理?

一句话结论

会话固定:登录成功后应更换会话标识/令牌,不沿用登录前的可预测会话;登出时服务端吊销当前令牌(加入黑名单或递增版本号),清除客户端 Cookie。敏感操作(改密、权限变更)后强制旧会话失效。

概念解释

  • 会话固定攻击:攻击者先持有会话 ID,诱使用户登录后复用该 ID 获得会话。
  • 无状态 JWT 登出依赖黑名单/版本号,令牌本身到期前仍有效。

原理流程

  1. 登录前会话标识不与登录后身份绑定。
  2. 认证通过签发新会话/新令牌,旧标识作废。
  3. 登出请求吊销当前凭证,清理客户端存储。
  4. 改密、解绑、权限降级后吊销相关会话。

代码或图示

@app.post("/auth/logout")
async def logout(token: str = Depends(oauth2_scheme)):
    payload = decode(token)
    await redis.setex(f"revoked:{payload['jti']}", token_ttl, "1")
    response = JSONResponse({"ok": True})
    response.delete_cookie("session")
    return response

常见误区

  • 登出只清前端 Cookie:服务端旧 token 仍可被持有使用。
  • 改密后不吊销旧会话:泄露会话在改密后继续有效。

追问

  • 怎么一次吊销用户所有设备会话?答:递增 token 版本号,旧令牌版本不符即拒。
  • 会话超时怎么配置?答:空闲超时 + 绝对超时双阈值,敏感业务缩短有效期。

04.7.15.4-058 服务间认证(mTLS / 内部 token)怎么做?

一句话结论

内部服务调用可用 mTLS(双向证书认证,网关/网格校验客户端证书)或内部服务 token(短期凭证,服务身份签发与轮换);凭证不暴露给外部,鉴权在网关/服务边界做。服务间权限按服务身份而非用户身份划分,日志记录调用方服务名。

概念解释

  • mTLS 验证双方证书,适合内网服务网格与强隔离场景。
  • 内部 token 轻量,但需管理签发、过期与吊销。

原理流程

  1. 服务身份凭证在部署时下发(证书/密钥)。
  2. 调用携带证书或 token,接收方在边界校验。
  3. 校验通过按服务身份授权可访问的接口范围。
  4. 审计记录调用方服务、时间与接口。

代码或图示

# 内部 token 依赖示例
async def require_internal(x_service_token: str | None = Header(default=None)):
    if not verify_service_token(x_service_token):
        raise HTTPException(401, "invalid service token")

常见误区

  • 内部接口直接裸奔无认证:内网被突破后横向移动无障碍。
  • 服务 token 长期有效且硬编码:泄露后难以及时吊销。

追问

  • mTLS 证书谁签发?答:内部 CA 或服务网格证书体系,定期轮换。
  • 用户上下文怎么透传给下游?答:在已认证内部调用基础上传递用户标识声明,下游再做边界校验。

04.7.15.4-059 OpenAPI schema 变更如何保持兼容?

一句话结论

向后兼容的变更:新增可选字段、新增接口、补充错误码说明;破坏性变更:删字段、改类型、改必填、改路径语义。演进时旧版本保留过渡期,模型新增字段给默认值,响应不缩窄字段;schema 变更与版本发布同步评审,客户端按版本适配。

概念解释

  • 兼容承诺面向调用方:文档 schema 是对外契约的一部分。
  • 字段废弃先标记、再下线,不直接删除。

原理流程

  1. 评审变更属于兼容还是破坏性。
  2. 兼容变更直接发布,模型字段可选并给默认值。
  3. 破坏性变更走新版本路由,旧版保留过渡期。
  4. 文档标注废弃状态与迁移指引。

代码或图示

# 兼容:新增可选字段
class ItemOut(BaseModel):
    id: int
    name: str
    description: str | None = None  # 新增可选,不破坏旧客户端

常见误区

  • 响应模型悄悄删掉字段:旧客户端解析缺失字段报错。
  • 把可选字段改成必填:旧请求体直接 422。

追问

  • 怎么检查 schema 差异?答:对比版本间 /openapi.json,字段增删、类型与必填变化纳入评审。
  • 废弃字段文档怎么标?答:描述中标注弃用版本与替代字段,过渡期后删除。

04.7.15.4-060 认证授权链路常被忽略的检查点有哪些?

一句话结论

清单:凭证校验是否覆盖签名/过期/iss/aud;资源归属是否在数据层隔离;401/403 是否区分;敏感字段是否从响应与文档剥离;令牌是否可吊销;限流与审计是否覆盖登录与敏感接口;密钥是否来自配置而非源码;文档入口生产是否关闭;内部接口是否有服务身份认证;模型约束是否与文档一致。

概念解释

  • 安全检查要沿“请求进入 → 认证 → 授权 → 业务 → 响应 → 文档”全链路走一遍。
  • 单点遗漏(如只做登录不做归属)即可造成越权。

原理流程

  1. 梳理公开/私有接口清单与各自主体维度。
  2. 逐接口核对认证依赖、权限规则与归属校验。
  3. 检查响应模型、文档 schema 与错误体不泄露内部信息。
  4. 验证令牌吊销、限流、审计与密钥管理落地。

代码或图示

公开接口 → 凭证依赖 → 用户加载 → 角色/scope → 资源归属 → 响应过滤 → 文档裁剪

常见误区

  • 只检查登录接口安全,忽略回调、内部任务、导出与批量接口。
  • 测试环境放宽安全策略后带进生产:按环境配置审查。

追问

  • 怎么做自动化安全回归?答:用测试用例覆盖未登录、越权、跨租户、伪造 token 等场景,纳入 CI。
  • 上线前安全评审看什么?答:认证授权链路、密钥与凭证管理、日志脱敏、文档暴露面与限流告警。

本节高频题

  • 认证方案对象与依赖分工(001、002、003)
  • API Key 与 SecurityScopes(004、005)
  • JWT 结构、声明校验与库选型(007、008、009)
  • 过期刷新、黑名单与令牌存储风险(010、011、039、040)
  • 密码哈希、盐值与时序攻击(013、014、015、016、018)
  • 注册登录流程与登录限流(017、041、055)
  • CORS 参数、凭证陷阱与预检(019、020、021)
  • 可信 Host、HTTPS 与 HSTS(022、023)
  • OpenAPI 生成流程与文档开关(024、025、029、051)
  • 自定义 openapi()、tags 与路由描述(026、027、028)
  • include_in_schema、示例与响应声明(030、031、032)
  • 安全方案与 scope 文档展示(033、034)
  • 依赖注入授权、角色工厂与多租户归属(035、036、037、038)
  • 401/403 区分与敏感字段隐藏(046、047、048)
  • 模型约束与 schema 关系(049、059)
  • 密钥轮换、审计日志与会话失效(042、043、057)
  • JWT 攻击防护、刷新轮换与服务间认证(053、054、058)