标签

#api-开发

2 篇文章

api-开发 fastapi gcp github k8s mcp nginx openai rag 上下文医学向量对话代码流式爬虫环境配置

2025年12月6日10 分钟

Catch-All 路由

Catch-All 路由指用 FastAPI 的 `/{full_path:path}` 这类 `path` 类型路径参数匹配任意层级 URL 的兜底路由，常见于前端 SPA 路由回退、后台管理插件或静态资源兜底处理。文章先区分了默认 `str` 参数只匹配单段路径，而 `path` 会连同斜杠一起接收多段路径，因此 `/api/does-not-exist` 这类未命中精确接口的请求不会直接 404，而可能进入 fallback 处理函数。重点风险在路由注册顺序：FastAPI 按注册先后匹配，若 SQLAdmin 等插件提前注册了 catch-all，后续业务 router 可能被截获，导致本应进入 `/api/v1/**` 的请求落到兜底逻辑。文章还把这种顺序问题和浏览器 CORS 报错关联起来，说明 OPTIONS 预检请求在目标接口未注册、被覆盖或 catch-all 不支持 OPTIONS 时，可能得到 404/405 且缺少跨域响应头，最终表现为跨域失败。处理方式包括先注册所有业务接口，再注册 SQLAdmin 或其他兜底路由，并让 catch-all 使用 `api_route(..., methods=["GET", "POST", "OPTIONS"])` 显式接住 OPTIONS。若不希望业务逻辑处理预检，也可以单独添加 `@router.options("/{full_path:path}")` 返回空响应，保证预检请求有合法 handler。适合正在排查 FastAPI 路由“莫名其妙被命中”、后台插件干扰 API、或未命中接口却显示 CORS error 的后端开发者参考。

api-开发

Python 开发

2025年12月6日13 分钟

接口等幂处理

接口等幂讨论的是 Web/API 在重复请求、自动重试或并发调用下如何避免重复修改系统状态，核心判断标准是同一操作执行多次后业务结果一致且不产生额外副作用。文章先用 HTTP 方法语义区分 GET、DELETE、PUT、POST 的等幂差异：查询、删除和“更新为固定状态”通常可视为等幂，而创建类 POST 容易产生重复资源，因此在支付、下单、扣积分等场景尤其需要防重。针对 PUT，文中强调理论语义和工程实现并不总是一致，即使请求体相同，也可能因 update_time、变更日志、审计表、MQ 消息、缓存刷新等动作破坏等幂。推荐做法是在更新前比较新旧数据，未变化时跳过写入和时间戳更新，或让日志、消息、缓存等副作用只在内容真正变更时触发。对于短时间重复提交或并发请求，文章给出基于 Redis 的幂等锁与状态缓存思路：用 idempotent key 标识一次操作，已处理则直接返回，未处理才执行业务逻辑。最后比较前端生成结构化 UUID 与后端令牌模式，认为完全随机 UUID 难以识别同一业务操作，而后端生成并下发幂等 key 更便于控制生命周期、缓存执行结果和保障支付、提交订单等关键接口的安全性。

api-开发