带编译期校验的复杂类型示例值：实践常规性与放置位置

你现在摸索的这套方案，根本不是没有先例的个人野路子，在静态类型主导、嵌套ADT结构复杂的代码库（比如Haskell、Rust、Scala这类语言的项目）里，这种写可编译无运行逻辑示例值的做法早就非常普遍：

• 它精准解决了纯文本文档的长期痛点：手写的示例没有任何约束，类型迭代之后文档里的结构很容易和实际实现脱节，新人照着文档拼出来的“合法值”往往一编译就报错；而你这种把示例纳入编译流程的方式，相当于给文档加上了强一致性保障，只要类型发生不兼容变更，示例会率先报编译错，维护者自然会同步调整示例，从机制上杜绝“文档和实现两张皮”的问题。
• 很多语言生态的文档工具本身就是为这类实践设计的：比如Haskell生态的Haddock、Rust的rustdoc，都原生支持嵌入可编译的代码示例，甚至强制要求这些嵌入的示例必须通过编译才能正常生成文档——本质逻辑和你现在写独立示例值完全一致，只是把独立定义的示例值，变成了文档块的一部分。
• 这类内容的定位从一开始就和业务逻辑、测试用例有清晰边界：它的核心作用是带编译校验的类型组装参考，既不需要承担运行时的业务职责，也不需要写断言来验证功能正确性，就是给开发者提供一个可以照着结构拼装合法值的参照模板。

这类内容既不适合混进生产业务逻辑，也不适合硬塞进测试目录，结合通用的仓库结构惯例，有几个适配度很高的放置选项：

• 最优先的选择：把示例嵌入到对应类型定义的文档注释中。比如你定义ApiResponseContent类型在哪个模块，就把对应的示例值用文档语法嵌到这个类型定义的上方注释里，和类型定义放在同一个文件。这种方式下，开发者在查看自动生成的类型文档时，就能直接看到对应的组装示例，而且全程被编译流程覆盖检查，完全不会侵入业务运行逻辑。
• 如果示例结构比较长、需要跨多个关联类型组合展示，可以单独建一个表意明确的独立模块，比如命名为Docs.TypeExamples，这个模块不对外导出给任何业务运行代码调用，只作为编译校验、文档参考的载体存在。现在很多代码库都会专门预留这类不带业务逻辑的文档支撑模块，专门存放这类可编译的示例值。
• 非常不推荐硬塞到测试目录：测试目录的代码默认语义是“通过断言验证业务逻辑正确性”，这类没有任何断言、纯做结构组装的示例放进去，会让维护测试的开发者困惑这段代码的测试目标是什么，既破坏了测试用例的语义清晰度，也没法让查阅文档的人第一时间找到这些参考值。
• 可以加个简单的编译配置避免误用：比如给示例模块加上对应的编译标记，明确告诉编译器这些值不需要作为公开接口导出，从根源上避免有人不小心把示例值当成正式的业务逻辑调用。

内容的提问来源于stack exchange，提问作者Jivan