如果 Swagger 正常工作，但你的 SDK 失效了，你的 SDK 在说谎

Source: Dev.to

设置

我在构建一个功能标记 / 运行时配置服务（在假期里做的一个有趣的项目）。
思路很简单：

• 后端按环境暴露配置值。
• SDK 在运行时获取这些值。
• 使用相同的 token、相同的环境、相同的键。

Swagger UI 完全正常，但 SDK 抛出了：

ConfigNotFoundError: config not found in environment 'development'

Swagger 并没有说谎——它展示了请求、请求头、解析后的环境以及正确的响应。

问题出在路由不匹配：

• 后端暴露的路由是：

  GET /api/v1/sdk/configs/{key}

• 我的 SDK 构造的 URL 是：

  /api/v1/config/{key}

SDK 静默返回了一个干净的 404，没有异常或警告，导致我浪费了数小时调试。

教训

• 你的 SDK 必须 逐字符 与后端路由保持一致。
• 如果需要提醒，就设置一个——否则你会花上好几天去追逐幻影 bug。

额外坑点

配置的存储形式是：

FEATURE_CHECKOUT_ENABLED

但 SDK 使用者可能会传入：

"feature_checkout_enabled"

这会导致：

• 缓存未命中
• 错误的 “未找到” 错误
• 结果不一致

解决办法： 对输入进行一次标准化，并在所有地方强制使用（在 API 调用前、缓存前、比较前）。

这次经历给我的启示

• Swagger 是你的合约。
• SDK 可以通过遗漏来撒谎。
• 路由不匹配是沉默的杀手。
• 标准化可以防止幻影 bug。
• 如果 Swagger 正常工作，后端就是无辜的。
• 先 Swagger，后 SDK，最后数据库。