Data Format（数据格式）

数据格式决定服务之间如何交换和持久化数据。解码只是把字节转换为 Go 值，不能代替业务校验；外部输入还必须定义大小、编码、空值、时区和版本兼容规则。

选择标准库编解码器

Go 标准库提供 encoding/json、encoding/csv、encoding/xml 等编解码器。优先使用协议实现，而不是用字符串切分拼装结构化数据。

• JSON 的 struct tag、流式编解码、数字精度和未知字段策略见 JSON 编解码。
• CSV 的引号、换行、字段数和流式处理见 CSV。

兼容性设计

新增字段通常应保持旧消费者可解码；删除或改变字段含义需要版本策略。明确哪些字段可缺失、null 与零值是否不同、时间使用何种时区和格式、金额使用最小整数单位还是 decimal 表示。对不可信输入设置请求体和单条记录大小限制。

TypeScript 的 JSON 类型或 schema 只能帮助生成静态提示；Go 解码后仍需校验必填字段、范围和业务约束。

常见错误

• 把 JSON 标签、Go 字段名和数据库列名混为一谈。
• 用浮点数承载金额或依赖默认时区。
• 认为解码成功就代表业务数据有效。
• 对不可信输入无限制地读取全部内容。
• 手写 CSV 分割逻辑，无法处理引号字段和嵌入换行。

小结

• 标准库编解码器优先于手写格式解析。
• 格式契约必须明确兼容性、精度、时区、空值和输入限制。
• 解码和业务校验是两个步骤。