配置、协议与 DSL
这篇解决什么问题
配置、协议与 DSL 解决的是系统之间如何用稳定、可读、可校验的文本或二进制格式表达规则、数据和接口。
这类主题通常不是单个工具或单条命令能讲清楚的，它更像一组工程约定：先明确问题边界，再选择合适模型、格式、流程或架构，最后通过测试、日志、指标和复盘确认方案真的可靠。
核心概念
| 概念 | 说明 |
|---|---|
| JSON | Web API 最常见的数据交换格式，结构简单，但不支持注释，日期和大整数需要额外约定。 |
| YAML | 适合配置文件，支持层级和注释，但缩进敏感，隐式类型容易踩坑。 |
| XML | 表达能力强，历史系统和企业集成中常见，但语法较冗长。 |
| TOML | 强调清晰配置，常见于 Rust、Python 等生态。 |
| CSV | 适合表格数据交换，但类型、转义和换行处理需要谨慎。 |
| Protobuf | 面向强 schema 的高效序列化，常用于 gRPC 和多语言服务。 |
| OpenAPI | 描述 REST API 的契约，可用于生成文档、客户端和测试。 |
| GraphQL Schema | 描述查询模型、类型和字段关系。 |
| Dockerfile | 描述镜像构建步骤。 |
| Nginx 配置 | 描述反向代理、路由、缓存和 TLS 等规则。 |
| HCL | Terraform 使用的基础设施描述语言。 |
它是怎么工作的
可以按四步理解：
- 识别对象：先确认要管理的是数据、接口、配置、请求、模型、流程还是团队协作。
- 建立契约：用 schema、接口规范、流程文档、测试用例或权限规则把隐含约定显式化。
- 执行与观测：让系统在真实运行中留下可追踪的证据，包括日志、指标、调用链、审计记录和变更记录。
- 反馈修正：根据错误、性能、成本和维护体验持续调整，而不是一次设计后永远不改。
这也是工程知识和纯概念知识最大的区别：概念本身不难，难的是在真实约束下做取舍，并且能证明选择是有效的。
关键设计问题
| 问题 | 为什么重要 |
|---|---|
| 边界在哪里 | 边界不清会导致职责扩散，后续维护困难 |
| 谁是调用方或使用者 | 不同使用者对可读性、性能、稳定性和权限的要求不同 |
| 失败时会怎样 | 没有失败模型，就无法设计重试、回滚、降级和告警 |
| 数据或状态是否会演进 | 版本兼容、迁移和历史数据处理往往比首次实现更难 |
| 如何验证 | 没有验证手段，AI 生成或人工设计都只能停留在“看起来合理” |
| 成本在哪里 | 成本包括机器资源、人力、认知负担和长期维护 |
开发中的真实场景
- 先识别问题属于配置、接口、数据、运行时、架构还是协作层面。
- 明确输入、输出、约束、失败模式和验收标准。
- 对关键路径保留日志、测试和文档，避免只靠口头经验传递。
- 遇到跨系统问题时，优先用事实链路排查，而不是按经验猜测。
- 当方案涉及多人协作时，把命名、目录、字段、错误码、权限和发布流程写成明确约定。
实践清单
- 写下当前问题的一句话目标。
- 列出输入、输出、依赖和不处理的范围。
- 明确正常路径、异常路径和边界条件。
- 为关键约定补充示例，而不是只写抽象定义。
- 能自动化验证的部分尽量放进测试、脚本或 CI。
- 不能自动化的部分保留人工验收清单。
- 变更后记录原因，避免后续只看到结果看不到取舍。
AI Coding 时代怎么用
- 让 AI 先解释现有系统中的相关约定，再要求它改动。
- 给出真实上下文：文件路径、配置、日志、接口样例和约束。
- 要求 AI 明确风险、边界和验证命令。
- 对高风险改动，坚持小步提交、测试验证和人工审查。
- 不要让 AI 在缺少上下文时自由发明标准；先让它读取现有文档、代码和配置。
- 对 AI 输出的术语、命令、配置和接口字段做事实校验。
常见误区
- 只记工具名，不理解工具解决的问题。
- 只追求通用性，提前做复杂抽象。
- 把 AI 生成的内容当成事实，缺少代码、测试或运行结果验证。
- 只写成功路径，不设计失败、重试、回滚和权限边界。
- 把文档当作交付物，而不是把文档当作团队协作的接口。
验证方式
- 能否用一个真实例子走完整条链路。
- 能否解释一个常见失败案例以及排查步骤。
- 能否指出这个方案不适合哪些场景。
- 能否通过测试、日志、指标、审计或人工 checklist 证明它在工作。
小结
配置、协议与 DSL 的重点不是背术语，而是理解它在真实工程链路中解决什么问题、带来什么约束，以及如何验证方案是否可靠。