API 与错误设计

先写公开契约

在实现前列出最小公共面：类型、常量、函数、参数顺序、返回形状、数据字段、错误代码和资源 上限。默认只导出用户需要组合的能力；解析内核、缓存、平台适配和校验辅助函数保持私有。

公开名称使用领域内一致、可搜索的中文词汇。不要同时发布多组含义相同的缩写和别名，也不要 让一个函数根据隐式全局状态返回不同形状。需要演进时，新增明确入口并保留旧入口至迁移窗口 结束。

公 定 版本：文 为 「1.0.0」；

公 定 默认限制：典 为 {
    「最大输入字符」：4096，
    「最大项目数」：1024
}；

公 法 解析（原文：文）：典 则
    # 校验、解析，并返回固定字段的典
终

公 法 尝试解析（原文：文）：典 则
    # 返回固定成功或失败信封，不把预期失败变成崩溃
终

文档要说明空值、Unicode、顺序、重复项、可变性、回调时机和并发所有权。若返回典或列， 固定字段名与元素语义；不要让调用方从打印文本中反向解析结果。

导出与包边界

清单中的默认导出决定引「包:言例」加载哪个文卷：

[导出]
默认 = "src/主.yx"
高级 = "src/高级.yx"

消费者可使用默认导出或显式导出，但不能依赖包内未声明的文件。用独立消费者验证这一点：

引「包:言例」为 言例；

定 结果 为 言例.解析（「示例」）；
言 结果；

不要在示例中直接引「../src/主.yx」。这种写法能掩盖漏导出、错误包名、锁文件错误和未 声明传递依赖。

稳定结构化错误

错误消息面向人，可以改善措辞；程序判断必须使用稳定代码。为库选择唯一前缀，例如 YANLI_，并提供错误详情把运行时错误转换为固定结构：

对常见的可预期失败，同时提供不抛出的尝试…入口。成功与失败信封应有固定键，且失败 不能携带半成品结果。无法识别的底层错误归一为明确的运行时代码，同时保留安全的诊断字段。

这些做法来自稳定库已经验证的模式：言版使用YANBAN_*，言章使用YANZHANG_*，HTTP 基础库使用YANXUN_*。前缀形式可以不同，但调用方绝不能依赖完整中文异常消息。

安全默认值与资源预算

任何接收外部输入的 API 都要回答四个问题：

1. 最大输入、深度、项目数、输出和迭代次数是多少？
2. 超限是明确失败，还是会产生截断后的伪成功？
3. URL、路径、SQL、HTML、命令参数等信任边界在哪里？
4. 错误、日志和踪迹是否会暴露令牌、密码、连接地址或原文？

公开默认预算，并为确需调整的调用方提供有上限的配置。未知配置键、负数、非整数或超过 硬上限的值都应返回配置错误。流式 API 若不能回滚已经交付的片段，要在契约中明确它不是 事务。

安全相关文本和结构必须使用正确的下层能力：SQL 值与 SQL 模板分离，HTML 默认转义， 动态标识符经过白名单，网络重定向剥离跨来源敏感首部。不要把“使用者应小心”当成缺失 边界检查的替代品。

可观测性不能泄密

日志和指标使用稳定事件名与结构化字段；默认对密码、Authorization、Cookie、令牌、证书 正文和完整连接地址脱敏。库不应在默认路径打印到标准输出。需要诊断时由调用方注入记录器， 并让关闭、重试、超时和取消事件具有可关联的请求编号。

生成 API 并阻止漂移

言序可以从公开声明生成 Markdown 和机器清单：

yanxu 文 src/主.yx docs/API.md
yanxu 文 --json src/主.yx api/api-v1.json

CI 应重新生成到临时位置并与提交版本逐字节比较。修改公开声明时，在同一功能提交中更新 API 制品、README、指南和规格；不要手改生成文件来隐藏漂移。

文档是兼容面的一部分

稳定库至少应维护：

• README.md：定位、安装、五分钟示例、错误、权限、兼容性与已知限制；
• docs/API.md与机器 API 清单：从源码生成；
• docs/GUIDE.md：常用组合与完整工作流；
• docs/ERRORS.md：错误代码、恢复策略与不可恢复状态；
• COMPATIBILITY.md：最低言序、依赖、平台、协议和明确不支持项；
• docs/SECURITY_MODEL.md与SECURITY.md：信任边界、安全默认值和私密报告方式；
• docs/ARCHITECTURE.md与docs/PERFORMANCE.md：所有权、复杂度、资源上限和基准条件。

记录已验证能力，也记录未实现能力。一次成功的本机实验不能证明“跨平台”“生产级”或 “兼容所有版本”；支持声明必须与 CI 和真实消费者的范围完全一致。

兼容性判断

安全收紧可能让过去接受的输入失败。即使 API 签名没变，也要评估是否破坏调用方，并在 CHANGELOG 与迁移指南中给出受影响输入和替代做法。