文档标准是成本计算的前提

文档混乱是成本失控的开始

大多数团队认为文档是事后工作。功能开发完成后，再补充文档。

这个顺序是错的。

文档不是代码的注释。它是系统设计的镜像。当文档混乱，通常说明设计混乱。当每个API的文档格式不同,成本计算就变成猜测。

统一的文档标准不是为了美观。它是为了让成本可预测。就像统一积分系统需要清晰的扣费规则,API文档需要统一的成本计算标准。

文档标准定义了什么

文档标准不是格式规范。它定义了三件事：

系统的边界。 每个参数的取值范围、每个响应的可能状态、每个错误的处理方式。这些边界决定了系统能承受多大的压力。

成本的结构。 基础成本、动态成本、倍率计算。这些数字不是凭空而来。它们来自厂商API的实际计费规则和你的利润目标。

可维护性。 统一的schema、一致的命名、标准化的示例。当所有文档遵循相同的模式,新人可以快速理解任何一个API。

为什么是60%利润率

利润率不是随意定的。

厂商API的成本是浮动的。网络可能超时。请求可能失败。重试会增加成本。如果利润率太低,一次失败就会吞掉所有利润。

60%的利润率提供了缓冲。它不是贪婪,是生存空间。

更重要的是,它让成本计算变得透明。当文档清楚地标注"厂商成本$0.08,用户消耗5积分,利润率75%",每个人都知道这个API是否健康。

积分必须是5的倍数

这个规则看起来武断,但它有深层原因。

认知负担。 5、10、20比6、13、18更容易记忆和计算。用户不需要精确计算就能估算成本。

定价灵活性。 5的倍数可以覆盖大部分成本区间,同时保持简洁。从5到100积分,只需要20个档位。

利润率验证。 当积分是5的倍数,验证利润率变得简单。credits * 0.0483 / vendor_cost >= 1.6。一眼就能看出是否达标。

// 成本计算示例
const vendorCost = 0.08  // 厂商API成本
const credits = 5        // 用户积分消耗
const revenue = credits * 0.0483  // Pro方案单积分价值

// 利润率验证
const profitMargin = (revenue - vendorCost) / revenue
// 结果: (0.2415 - 0.08) / 0.2415 = 66.9%

// ✅ 符合60%目标

参数归一化是用户体验的基础

厂商API的参数命名不统一。OpenAI用guidance_scale,Fal用guidance,KIE可能用cfg_scale。

如果直接暴露这些差异,用户需要学习每个厂商的特殊语法。这是糟糕的体验。

参数归一化解决这个问题。系统定义统一的参数名和范围,然后映射到厂商的实际参数。

{
  "guidance_scale": {
    "ui_range": [0, 100],
    "vendor_range": [1, 20],
    "transform": "linear"
  }
}

用户看到的是0-100的滑块。系统自动转换为厂商需要的1-20。

这不是隐藏复杂性。这是管理复杂性。

监控和追踪让文档变得活的

文档可以定义标准,但只有监控才能验证标准是否被遵守。

每个API调用应该记录：

• trace_id: 全链路追踪标识
• credits_consumed: 实际积分消耗
• vendor_cost: 厂商API成本
• profit_margin: 实际利润率
• status: 成功、失败、重试

当利润率持续低于60%,说明成本计算有问题。当某个API的失败率异常,说明参数映射可能错误。

文档定义了"应该是什么",监控揭示了"实际是什么"。

DLQ是失败处理的最后防线

Dead Letter Queue不是错误收集器。它是系统韧性的体现。

当API调用失败,有三种可能：

1. 临时故障,重试可能成功
2. 参数错误,重试永远失败
3. 厂商故障,等待恢复

DLQ帮助区分这三种情况。它记录失败的请求、失败原因、重试次数。它让人工介入变得可能。

更重要的是,它保护用户的积分。失败的任务会自动退款。用户不会为失败付费。

文档标准是持续演进的

没有完美的文档标准。只有持续改进的标准。

当新的厂商接入,可能需要新的参数类型。当成本结构变化,利润率目标可能需要调整。当监控揭示新的问题,文档需要增加新的章节。

文档标准不是一次性工作。它是系统知识的沉淀。

每次更新版本号,说明系统又学到了新东西。V5.1.0不只是数字。它代表了对V5.0.0的反思和改进。

最后

API文档标准不是官僚主义。

它是让复杂系统可管理的工具。当有10个API时,你可以记住每个的特殊规则。当有100个时,你需要标准。

标准化让扩展成为可能。它让成本透明。它让新人快速上手。它让监控有意义。

这就是文档标准的价值。不是为了整齐,是为了生存。