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)。认证逻辑复用普通依赖,不引入特殊装饰器。
概念解释
- 安全方案只负责“提取凭证”,校验与用户加载在依赖函数里完成。
- 方案对象可被多个路由共享,统一凭证来源与错误响应。
原理流程
- 实例化安全方案,指定凭证位置(头/查询参数/表单)。
- 编写依赖:从方案取 token → 校验 → 查用户 → 返回用户对象。
- 路由用
Depends注入该依赖,未通过则抛 401/403。 - 方案元数据自动进入 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,用于可选登录场景。
原理流程
- 方案被依赖调用,读取
Authorization头。 - 头缺失或格式不符:
auto_error=True抛 401;否则返回 token 字符串。 - 依赖把 token 交给校验函数解析签名与声明。
- 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 安全方案类型不同:
httpscheme 与oauth2flow。 - 运行时提取行为基本一致,差别主要在文档表达。
原理流程
- 实例化对应方案,声明 bearer 格式与可选 realm。
- 依赖调用方案解析头,返回
HTTPAuthorizationCredentials或 token 字符串。 - 校验凭证后返回用户。
- 文档按方案类型生成
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。
原理流程
- 实例化对应位置的 API Key 方案。
- 依赖提取 key,查配置/存储中的有效 key 集合。
- 校验通过返回调用方身份,否则 401。
- 方案写入 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 是用户实际授予的集合。
原理流程
- 实例化方案时传入
scopes=[Scope(...)]。 - 依赖注入
SecurityScopes,读取要求范围。 - 解析 token 得到授予范围,做包含校验。
- 文档把 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 错误。
原理流程
- 安全方案提取凭证字符串。
- 校验签名、过期、签发方等声明。
- 按
sub查用户,校验账号状态。 - 返回用户模型;任一环节失败抛 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 是自包含令牌,服务端校验签名即可,不必每次查会话存储。
原理流程
- 头部声明
alg(如 HS256)与typ: JWT。 - 载荷写入业务声明与过期时间。
- 用密钥按算法对
header.payload计算签名。 - 服务端解码后用同密钥/公钥验签,再检查声明有效性。
代码或图示
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=[...])。 - 依赖选型要结合团队维护、安全补丁与目标算法支持。
原理流程
- 按算法与密钥形态选择库。
- 签发:构造 payload,指定算法与密钥生成 token。
- 验签:传入允许的算法白名单与密钥,解码并校验声明。
- 验签失败抛库特定异常,依赖转成 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 参数。
原理流程
- 用密钥与算法白名单验签,签名失败即拒。
- 校验
exp/nbf时间声明。 - 校验
iss/aud与本服务配置匹配。 - 加载
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。
原理流程
- 登录成功签发短寿命 access 与长寿命 refresh。
- 业务接口 access 过期返回 401,客户端调刷新端点。
- 校验 refresh 签名、过期、吊销状态与绑定关系。
- 签发新 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)可一次吊销某用户全部旧令牌。
原理流程
- 签发时写入唯一
jti与用户 token 版本。 - 登出/下线时把
jti或版本号加入存储,设 TTL。 - 校验时先验签,再查黑名单/版本是否失效。
- 命中即拒,返回 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。
概念解释
- 保密性与完整性是两回事:签名防篡改,不防读取。
- 授权变更要生效,需要吊销旧令牌或等待其过期。
原理流程
- 签发前审查 payload 字段,剥离敏感与易变数据。
- 身份类信息(
sub、scopes)放令牌。 - 业务状态在请求到达后查库获取。
- 权限变更走吊销/版本轮换机制。
代码或图示
# 不推荐
{"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),通过工作因子拉长单次计算成本,并带随机盐。
概念解释
- 快速哈希让“猜密码”也变快,与存储安全目标相反。
- 慢哈希可调成本:随硬件升级提高迭代次数/内存参数。
原理流程
- 注册时生成随机盐,用慢哈希计算密码摘要。
- 存储哈希与算法参数,不存明文与盐副本(盐通常编码在哈希串内)。
- 登录时用相同盐与参数重算,常量时间比对。
- 暴力破解单次成本被工作因子拉高。
代码或图示
# 不推荐:快速哈希
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 等)。
- 算法选择要考虑依赖维护、部署环境与历史数据迁移。
原理流程
- 注册:按选定算法与参数计算哈希串(含盐与成本参数)。
- 校验:从哈希串解析参数,重算并比对。
- 算法升级:登录校验通过后可用新参数重哈希(rehash)平滑迁移。
- 配置记录所用算法,便于后续调参与迁移。
代码或图示
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 封装问题。
- 预哈希要在服务端固定实现,不能依赖客户端行为。
原理流程
- 注册:密码先经 SHA-256 摘要,再交 bcrypt 哈希。
- 登录:相同预处理后重算比对。
- 超长密码不受截断影响。
- 更换算法时同步调整预处理流程。
代码或图示
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),使耗时与匹配程度无关,避免侧信道泄露。
概念解释
- 侧信道不依赖攻破算法,而依赖运行行为(耗时、响应差异)。
- 网络噪声会降低远程时序攻击精度,但本地与内网场景仍需防护。
原理流程
- 攻击者提交逐位变化的凭证,测量响应耗时。
- 普通比较在失配处短路返回,匹配位越多耗时略长。
- 据此逐位推断有效前缀。
- 常量时间比较遍历全部字节,耗时不随匹配度变化。
代码或图示
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 比对 → 成功签发令牌,失败返回统一错误(不区分“用户不存在”与“密码错误”)。哈希计算放线程池,避免阻塞事件循环。
概念解释
- 统一登录失败消息防止用户名枚举;响应时序也应尽量一致。
- 密码字段在用户模型与响应模型中排除,避免回传。
原理流程
- 注册:强度校验 →
pwd_context.hash→ 存哈希串。 - 登录:查用户 →
verify比对哈希。 - 校验通过生成 access/refresh;失败抛 401 统一消息。
- 记录登录审计(成功/失败、来源 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 随机盐如何防护彩虹表与同密码碰撞?
一句话结论
盐是注册时生成的随机值,与密码一起送入慢哈希;同一密码在不同用户名下产生不同哈希,预计算的彩虹表无法复用反查。盐不需要保密,通常编码在哈希串内随哈希一起存储;关键是每个用户独立、足够随机。
概念解释
- 盐防“批量反查”,慢哈希防“单条暴力”,两者互补。
- 盐长度不足或可预测会削弱防护,应使用密码学随机源生成。
原理流程
- 注册生成随机盐(库内部自动完成)。
- 盐 + 密码经慢哈希得到摘要,盐与参数编码进哈希串。
- 登录从哈希串解析盐与参数,重算比对。
- 相同密码因盐不同得到不同存储值。
代码或图示
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 当访问控制。
原理流程
- 浏览器请求带
Origin,中间件比对白名单。 - 命中则在响应追加
Access-Control-Allow-Origin等头。 - 复杂请求先发 OPTIONS 预检,中间件回应方法/头/凭证许可。
- 预检通过后浏览器才发送实际请求。
代码或图示
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、客户端证书)下,浏览器强制要求精确源匹配。
- 中间件在凭证开启时会按请求源回显,而不是发
*。
原理流程
- 配置凭证开启,源白名单为具体域名。
- 预检/实际请求带来源头,中间件命中后回显该源。
- 响应同时带允许凭证标记。
- 通配符 + 凭证组合被浏览器拦截,前端表现为跨域报错。
代码或图示
# 错误组合:凭证开启 + 通配符源
# 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 + 表单/文本头)不发预检,直接发实际请求。
- 预检不带业务凭证语义,处理不当会导致真实请求被浏览器阻止。
原理流程
- 浏览器判断请求为复杂类型,先发 OPTIONS。
- 中间件提取请求方法/头,比对白名单。
- 返回
Access-Control-Allow-Methods/Headers/Origin/Credentials,状态 200/204。 - 预检通过后发送实际请求;缓存期内不再预检。
代码或图示
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 取决于转发配置,需要统一约定。
原理流程
- 配置 Host 白名单(域名列表,支持通配规则按实现确认)。
- 请求进入中间件,比对
Host头与白名单。 - 不匹配返回 400,不进入业务。
- 反代层正确传递 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 版本与套件在代理/负载均衡层管理,应用不重复终止。
原理流程
- 代理监听 80/443,80 跳转 443。
- HTTPS 响应追加 HSTS 头(
max-age、可选includeSubDomains、preload)。 - 浏览器记住策略,后续直接 HTTPS 访问。
- 应用通过
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 模型,不需要手写接口描述。
- 依赖中的参数同样会进入文档(除非隐藏)。
原理流程
- 应用启动后收集全部路由的路径、方法、处理器引用。
- 解析函数签名与依赖,提取参数来源(path/query/body/header/cookie)。
- 用 Pydantic 模型生成 JSON Schema,组合安全方案与响应声明。
- 汇总成 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 仍可能被访问,需同时处理。 - 多应用挂载时各实例有独立文档路径。
原理流程
- 构造
FastAPI(...)时传入文档路径或None。 - 框架按配置注册文档路由。
- 访问对应路径返回 UI 或 schema。
- 生产环境按部署策略关闭或保护文档入口。
代码或图示
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 报错。
原理流程
- 定义生成函数:调用
FastAPI.openapi基类逻辑得到 schema。 - 遍历
paths/components.schemas做定制。 - 结果缓存到实例属性,重复调用直接返回。
- 把函数挂到
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 中未声明的标签仍会出现在文档,只是没有补充描述。
原理流程
- 构造应用时定义
tags_metadata列表。 - 路由用
tags=[...]标记归属。 - 生成 schema 时按标签聚合操作,附带描述。
- 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中声明。
原理流程
- 路由装饰器填写标题与说明文字。
- 生成 schema 时映射到 Operation 的
summary/description/responses描述。 - UI 在接口卡片展示标题、正文与成功响应说明。
- 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 或本地化部署。
原理流程
- 框架注册两个文档页面路由。
- 页面加载后请求
openapi_url的 schema。 - Swagger 渲染可执行表单;ReDoc 渲染分组文档。
- 后端 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 组件中消失。
原理流程
- 路由标记
include_in_schema=False。 - 生成 schema 时跳过该操作条目。
- 文档不展示,但服务器仍匹配并执行该路由。
- 接口保护通过认证/网络策略另行实现。
代码或图示
@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。
原理流程
- 在路由参数或模型字段上填写示例值。
- 生成 schema 时写入请求/响应的
example(s)。 - UI 渲染示例下拉与预填表单。
- 示例值不参与运行时校验,仅作文档展示。
代码或图示
@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 组件复用。
原理流程
- 列出端点可能返回的全部状态码。
- 为每个错误状态码指定模型与描述。
- 生成 schema 时合并成功响应与补充响应。
- 文档展示各分支结构,客户端按码处理。
代码或图示
@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 →oauth2flow;API Key →apiKey。 - 未被任何依赖引用的方案不会进入 schema。
原理流程
- 实例化安全方案并在依赖中
Depends引用。 - 生成 schema 时收集方案元数据到
securitySchemes。 - 路由操作追加
security引用,绑定方案与 scope。 - 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。
原理流程
- 方案定义可用 scope 与中文描述。
- 路由声明要求的 scope 列表。
- schema 合并方案 scope 与操作所需 scope。
- 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):你能做什么。
- 可复用依赖让权限变更集中修改,避免遗漏端点。
原理流程
get_current_user完成凭证校验与用户加载。- 权限依赖(如
require_roles("admin"))接收用户并判断。 - 不满足抛 403;未认证由认证依赖抛 401。
- 端点只接收已授权用户/资源对象。
代码或图示
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 级别批量挂载一组依赖,路由只声明所需角色。
概念解释
- 依赖工厂返回新的依赖函数,闭包保存角色/权限参数。
- 路由组统一挂依赖,组内端点无需重复书写。
原理流程
- 定义认证依赖返回用户对象。
- 工厂函数
has_role(role)返回校验依赖。 - 资源依赖读取路径参数,查资源归属后比对用户。
- 路由器或端点按需要注入对应依赖。
代码或图示
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。租户上下文从认证信息派生,不信任请求体中的租户字段。
概念解释
- 越权分水平越权(访问他人同层数据)与垂直越权(访问高权限功能)。
- 数据层查询条件带租户/用户隔离,是归属校验的最后一道防线。
原理流程
- 认证依赖解析出用户 ID 与租户 ID。
- 服务层按
resource_id + tenant_id/user_id查询。 - 未查到或归属不符抛 404/403。
- 响应模型不跨租户暴露敏感字段。
代码或图示
@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:框架解析共享依赖并按拓扑顺序执行。
- 同一依赖在链路中默认结果缓存(同一次请求内复用)。
原理流程
- 解析端点参数与依赖树。
- 先执行认证依赖,得到用户对象。
- 授权、资源依赖注入用户与路径参数继续校验。
- 任一依赖抛错即中断,不进入端点函数体。
代码或图示
@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、服务端渲染、移动端)相关。
原理流程
- 登录后按架构选择令牌存储位置。
- 前端做好输入输出转义与 CSP,降低 XSS 面。
- Cookie 方案配置 SameSite、HttpOnly、Secure 与 CSRF 防护。
- 令牌短寿命 + 可吊销,降低泄露后影响窗口。
代码或图示
localStorage:JS 可读,XSS 即泄露
内存:刷新丢失,XSS 当次可读取
HttpOnly Cookie:JS 不可读,需防 CSRF
常见误区
- 以为存 Cookie 就免做 CSRF:自动携带特性反而引入跨站伪造风险。
- 只靠前端藏 token:后端必须按短寿命、吊销、限流做纵深防御。
追问
- 移动端原生应用存哪里?答:系统安全存储(Keychain/Keystore),不写普通明文配置。
- XSS 防护包括哪些?答:输出转义、CSP、富文本清洗、依赖漏洞更新、避免内联脚本。
04.7.15.4-040 Cookie 会话与 Bearer Token 的安全取舍?
一句话结论
Bearer Token 便于 SPA/移动端携带与跨域调用,但存储风险自担;Cookie 会话由浏览器管理、HttpOnly 防脚本读取,但需处理 CSRF、SameSite 与跨域配置。同站前后端推荐 Cookie + CSRF 防护;跨域 API/多端客户端常用 Bearer + 短令牌。
概念解释
- Cookie 随请求自动携带;Bearer 由前端手动放入
Authorization头。 - 会话型服务端可查可吊销;JWT 无状态但吊销依赖黑名单。
原理流程
- 按部署形态(同站/跨域/多端)选择凭证传递方式。
- Cookie 方案配置安全属性与 CSRF Token。
- Bearer 方案在响应中返回 token,前端按安全位置保存。
- 服务端校验逻辑一致,差别在凭证来源与防护重点。
代码或图示
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 与账号双维度限制。
原理流程
- 入口识别主体维度(IP/账号/key)。
- 读取窗口内失败计数与配额。
- 超限返回 429 或锁定提示;成功后清零失败计数。
- 记录失败事件用于审计与告警。
代码或图示
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)私钥签发、公钥分发验签。
- 密钥进入日志、错误信息或文档都是泄露面。
原理流程
- 启动时从配置/密钥服务加载当前私钥与可选历史公钥。
- 签发时写入
kid标识密钥版本。 - 验签按
kid选择对应密钥,算法白名单校验。 - 轮换期新旧密钥并存,旧令牌平滑过渡后下线旧密钥。
代码或图示
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,不记录密码、完整令牌与敏感参数。日志集中存储并接入告警,异常批量失败触发排查。
概念解释
- 审计日志面向事后追责与安全告警,与业务访问日志粒度不同。
- 日志本身要防篡改与越权读取。
原理流程
- 认证/授权依赖在关键节点写审计事件。
- 字段填充主体、来源、结果与关联 ID。
- 敏感字段脱敏后落库/日志系统。
- 规则匹配异常模式(批量失败、异地登录、越权尝试)并告警。
代码或图示
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 登录。
原理流程
- 重定向到 IdP 授权地址,携带
client_id、redirect_uri、state、scope。 - 用户登录授权,IdP 回调本地路由并附
code。 - 后端用 code + 客户端密钥向 token 端点换令牌。
- 取用户信息,绑定/创建本地用户,签发本地会话令牌。
代码或图示
@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与注册地址一致。
原理流程
- 生成随机 state,关联本地会话上下文并缓存。
- 授权 URL 携带 state。
- 回调取回 state,查缓存比对并消费(一次性)。
- 校验通过再换令牌;失败记录审计并拒绝。
代码或图示
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 策略)。
原理流程
- 认证依赖解析凭证,缺失/无效抛 401。
- 用户加载成功后进入授权校验。
- 角色/scope/归属不足抛 403。
- 响应经统一异常处理器格式化。
代码或图示
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 模型分层是隐藏敏感字段的基础。
- 文档可见范围 = 被路由响应模型与请求模型引用的字段集合。
原理流程
- 定义
XxxIn/XxxOut模型,只暴露对外字段。 - ORM 实体映射到 Out 模型,敏感字段不参与序列化。
- 响应类型标注为 Out 模型。
- 必要时自定义
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 规则。
原理流程
- 路由标注
response_model=ItemOut。 - 运行时:返回值经模型校验与字段过滤后序列化。
- 生成文档:模型转 JSON Schema 写入响应定义。
- 客户端按 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组件定义。
原理流程
- 定义模型字段类型与
Field约束。 - 框架调用模型的 JSON Schema 生成能力。
- 约束、必填、示例写入 OpenAPI 组件。
- 文档展示校验规则,客户端据此生成表单与类型。
代码或图示
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 路由层最直接支持前缀方案。
- 多版本共享模型时注意字段演进不要破坏旧契约。
原理流程
- 按版本创建 APIRouter,设置前缀与标签。
- 路由挂载到主应用对应路径。
- OpenAPI 按标签聚合各版本接口。
- 旧版本接口标记弃用,保留过渡期后下线。
代码或图示
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 保护文档,而不是简单依赖页面隐藏。关闭前确认联调渠道,保留最小内部可见性。
概念解释
- 文档泄露接口结构、模型字段与内部路径,是信息收集入口。
- 环境差异通过配置注入,不在代码里硬编码开关。
原理流程
- 按环境配置文档开关与路径。
- 生产关闭三个文档入口,或加认证/来源限制。
- 内部联调通过受保护环境访问文档。
- 上线前检查
/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 相关的授权适合依赖。中间件做前置过滤,依赖做细粒度判定;两者可叠加,但不要在中间件里重复实现资源级权限。
概念解释
- 中间件在路由匹配前执行,拿不到路径参数与路由声明。
- 依赖能访问参数、模型与注入上下文,适合业务授权。
原理流程
- 中间件解析全局凭证,缺失则短路 401。
- 请求进入路由,认证依赖加载用户。
- 授权依赖结合参数校验角色/归属。
- 端点执行已授权业务。
代码或图示
# 中间件:全局凭证存在性检查
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算法早期规范允许无签名,实现必须显式拒绝。
原理流程
- 签发时确定算法与密钥类型。
- 验签传入固定
algorithms白名单与对应密钥。 - 库按白名单校验签名,头部算法不在列表即拒绝。
- 检查
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 即判定泄露,吊销该用户全部会话。轮换链断裂/重复使用旧令牌触发安全告警。
概念解释
- 轮换缩小泄露令牌可用窗口;重放检测发现令牌被窃取后重复使用。
- 刷新令牌绑定设备/客户端信息,异地异客户端使用标记可疑。
原理流程
- 登录签发 refresh,记录其
jti与用户/设备绑定。 - 刷新时校验 jti 有效,签发新 refresh,旧 jti 作废。
- 若收到已作废 jti:判定重放,吊销该用户所有令牌并告警。
- 绑定信息(设备、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 阈值不够,需多维度信号。
原理流程
- 登录入口记录失败次数、来源与账号维度。
- 超阈值触发验证码/临时锁定/二次验证。
- 检测批量模式:同 IP 多账号、同账号多来源、高频失败。
- 可疑会话强制重认证,安全事件入审计并告警。
代码或图示
# 多维度计数示例
await redis.incr(f"fail:ip:{ip}")
await redis.incr(f"fail:user:{username}")
# 任一维度超阈值 → 验证码/锁定/风控拦截
常见误区
- 只靠密码复杂度:用户复用泄露密码,复杂度高也会被撞中。
- 锁定只按账号:攻击者轮换账号绕过;只按 IP:NAT 误伤。
追问
- 怎么判断一批尝试是撞库?答:失败率高、密码分布集中、来源分散、账号集合大。
- 二次验证(2FA)在防护中的位置?答:作为凭证泄露后的第二道防线,敏感账号强制开启。
04.7.15.4-056 密码策略与强度校验怎么定?
一句话结论
策略包含最小长度、字符类别要求、弱口令黑名单、禁止与账号信息雷同、定期更换(按业务风险);注册与改密时校验强度,校验结果给出明确字段级提示。服务端强制策略,前端提示仅为体验补充。
概念解释
- 强度平衡安全性与可记忆性:过长过复杂导致用户写便利贴或复用。
- 泄露密码库校验比静态规则更能拦截真实弱口令。
原理流程
- 设定长度与类别规则、弱口令/泄露密码名单。
- 注册/改密接口在哈希前校验密码。
- 不满足返回字段级错误,说明缺口。
- 校验通过后慢哈希入库。
代码或图示
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 登出依赖黑名单/版本号,令牌本身到期前仍有效。
原理流程
- 登录前会话标识不与登录后身份绑定。
- 认证通过签发新会话/新令牌,旧标识作废。
- 登出请求吊销当前凭证,清理客户端存储。
- 改密、解绑、权限降级后吊销相关会话。
代码或图示
@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 轻量,但需管理签发、过期与吊销。
原理流程
- 服务身份凭证在部署时下发(证书/密钥)。
- 调用携带证书或 token,接收方在边界校验。
- 校验通过按服务身份授权可访问的接口范围。
- 审计记录调用方服务、时间与接口。
代码或图示
# 内部 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 是对外契约的一部分。
- 字段废弃先标记、再下线,不直接删除。
原理流程
- 评审变更属于兼容还是破坏性。
- 兼容变更直接发布,模型字段可选并给默认值。
- 破坏性变更走新版本路由,旧版保留过渡期。
- 文档标注废弃状态与迁移指引。
代码或图示
# 兼容:新增可选字段
class ItemOut(BaseModel):
id: int
name: str
description: str | None = None # 新增可选,不破坏旧客户端
常见误区
- 响应模型悄悄删掉字段:旧客户端解析缺失字段报错。
- 把可选字段改成必填:旧请求体直接 422。
追问
- 怎么检查 schema 差异?答:对比版本间
/openapi.json,字段增删、类型与必填变化纳入评审。 - 废弃字段文档怎么标?答:描述中标注弃用版本与替代字段,过渡期后删除。
04.7.15.4-060 认证授权链路常被忽略的检查点有哪些?
一句话结论
清单:凭证校验是否覆盖签名/过期/iss/aud;资源归属是否在数据层隔离;401/403 是否区分;敏感字段是否从响应与文档剥离;令牌是否可吊销;限流与审计是否覆盖登录与敏感接口;密钥是否来自配置而非源码;文档入口生产是否关闭;内部接口是否有服务身份认证;模型约束是否与文档一致。
概念解释
- 安全检查要沿“请求进入 → 认证 → 授权 → 业务 → 响应 → 文档”全链路走一遍。
- 单点遗漏(如只做登录不做归属)即可造成越权。
原理流程
- 梳理公开/私有接口清单与各自主体维度。
- 逐接口核对认证依赖、权限规则与归属校验。
- 检查响应模型、文档 schema 与错误体不泄露内部信息。
- 验证令牌吊销、限流、审计与密钥管理落地。
代码或图示
公开接口 → 凭证依赖 → 用户加载 → 角色/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)