1. 基本数据结构#

YAML 的数据结构与 JSON 对应：

• 对象（映射、map）：key: value
• 数组（序列、list）：

  1
  fruits:
  2
    - apple
  3
    - banana
  

• 标量（scalar）：字符串、数字、布尔、null、时间等。

YAML 强依赖缩进表达层级：只用空格，不要用 Tab。团队应统一 2 或 4 个空格缩进。

2. 字符串与数字#

• 普通字符串可不加引号；包含冒号、前导零、布尔词、特殊字符时建议加引号，避免被误解析：

  1
  code: "01"        # 避免被当作数字
  2
  enabled: "off"    # 避免被当作 false（YAML 有多种布尔字面量）
  3
  path: "/v1/users" # 含斜杠更安全
  

• 多行字符串有两种常用块标量：

  1
  desc: |
  2
    第一行
  3
    第二行
  4
  note: >
  5
    这一段
  6
    渲染为单行
  

  | 保留换行；> 折叠换行为空格。可用 |-、|+ 控制末尾换行修剪。

3. 数组与对象的行内写法#

• 行内（flow）风格与 JSON 类似：

  1
  obj: {a: 1, b: 2}
  2
  arr: [1, 2, 3]
  

• 多数配置建议使用缩进（block）风格，可读性更高。

4. 引用、锚点与合并（进阶）#

• 复用片段：

  1
  base: &base
  2
    retries: 3
  3
    timeout: 5s
  4
  server:
  5
    <<: *base
  6
    timeout: 10s
  

  合并键 << 会把 base 的键值并入 server。 注意：不同工具对锚点/合并支持不完全一致，写 OpenAPI 时尽量谨慎使用。

5. 注释与文件后缀#

• 注释用 #。
• .yaml 与 .yml 完全等价，二者只是扩展名不同。实践中各生态有约定俗成：如 docker-compose.yml、Kubernetes 常见 .yaml。

1. 使用 gopkg.in/yaml.v3#

适合直接把 YAML 映射到结构体。

1
type Server struct {
2
    Host string `yaml:"host"`
3
    Port int    `yaml:"port"`
4
}
5
type Config struct {
6
    Server Server `yaml:"server"`
7
}
8

9
data, err := os.ReadFile("config.yaml")
10
if err != nil { /* handle */ }
11
var cfg Config
12
if err := yaml.Unmarshal(data, &cfg); err != nil { /* handle */ }

要点与常见问题：

• 结构体标签用 yaml:"fieldName"；未匹配的字段会被忽略。
• 建议在解析前设置默认值（或使用 viper 的默认值能力）。
• 对可能缺省的字段，使用指针类型可区分“没填”和“零值”。
• 时间、持续时间等：time.Duration 在 YAML 中以字符串表示（如 "5s"），解析时可用自定义类型或中间字符串再转换。
• 严格模式：社区常见做法是加载后对未识别键进行二次校验（如先反序列化到 map[string]any 做白名单检查），或在 CI 用 schema 校验配置。

2. 使用 github.com/spf13/viper#

适合复杂项目的“配置中心”方案：多格式、环境变量覆盖、默认值、可选热加载。

1
viper.SetConfigName("config")
2
viper.SetConfigType("yaml")
3
viper.AddConfigPath(".")
4
if err := viper.ReadInConfig(); err != nil { /* handle */ }
5

6
viper.SetDefault("server.port", 8080)
7
viper.AutomaticEnv()
8
viper.SetEnvPrefix("APP") // APP_SERVER_PORT=9090
9
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
10

11
var cfg Config
12
if err := viper.Unmarshal(&cfg); err != nil { /* handle */ }

实践建议：

• 配置层叠：基础配置 + 环境覆盖。例如 config.yaml、config.dev.yaml，再用环境变量兜底。
• 明确配置优先级：默认值 < 文件 < 环境变量 < 命令行参数。
• 若启用热加载，记得设计并发安全的配置读取方式（例如原子替换）。

1. 文档与服务层面#

• openapi: 规范版本。

• info: 文档元信息，含 title、description、version 等。

• servers: 一组基础 URL，可用 variables 定义模板变量及默认值。

  1
  servers:
  2
    - url: "https://{host}/api"
  3
      variables:
  4
        host:
  5
          default: "example.com"
  

2. 路由与操作（paths 与 HTTP 动作）#

• paths 的键是路径模板，形如 /users/{id}。

• 每个路径下可定义 get、post、put、delete、patch 等操作。

• 操作级字段常见：

  • summary、description：人类可读说明。
  • tags：分组标签。
  • operationId：全局唯一的操作标识，代码生成器常用它生成方法名。
  • parameters：参数列表（path/query/header/cookie）。
  • requestBody：请求体描述及媒体类型。
  • responses：响应状态码映射。
  • security：操作级安全策略（可覆盖全局）。
  • servers：操作级覆盖的服务器地址（可选）。

3. 参数（parameters）#

• 位置：in 为 path、query、header、cookie。

• 路径参数必须 required: true，且名称与路径模板占位符一致。

• 序列化控制：

  • style、explode、allowReserved 等影响数组/对象在查询串或头部的编码方式（如 form、simple、pipeDelimited、spaceDelimited 等）。

• 类型通过 schema 指定，支持 type、format、enum 等。

示例（查询参数数组的不同风格）：

1
parameters:
2
  - in: query
3
    name: ids
4
    schema:
5
      type: array
6
      items: { type: string }
7
    style: form
8
    explode: true    # ?ids=a&ids=b

4. 请求体（requestBody）#

• required: 是否必须。
• content: 媒体类型到 schema 的映射，例如 application/json、multipart/form-data、application/x-www-form-urlencoded、text/plain。
• 对上传文件，在 3.0 中常用 type: string, format: binary，配合 multipart/form-data。

5. 响应（responses）#

• 键为状态码字符串（建议加引号避免 YAML 把 200 解析成数字）。
• default 为兜底响应。
• headers 可定义响应头。
• content 定义不同媒体类型的 schema。

示例：

1
responses:
2
  "200":
3
    description: ok
4
    content:
5
      application/json:
6
        schema:
7
          $ref: "#/components/schemas/User"
8
  default:
9
    description: error

6. 复用部件（components）#

常见子节：

• schemas：数据模型（强烈建议集中管理）。
• parameters：可复用的参数定义。
• responses：可复用的响应。
• requestBodies、headers、examples、securitySchemes、links、callbacks 等。

$ref 用法：

1
schema:
2
  $ref: "#/components/schemas/User"

OpenAPI 3.0 中 $ref 节点不能与并列的其他键共存；3.1 放宽，但生成器支持度不一，务必验证。

1. 基本类型与格式#

1
type: string
2
type: integer
3
  format: int32     # 也可 int64
4
type: number
5
  format: float     # 或 double
6
type: boolean
7
type: array
8
  items: { $ref: "#/components/schemas/User" }
9
type: object
10
  properties: { ... }

Go 常见映射（生成器可能略有差异）：

• string → string
• integer(int32) → int32 或 int
• integer(int64) → int64
• number(float/double) → float32/float64
• boolean → bool
• array[T] → []T
• object → struct 或 map[string]any（有时 additionalProperties 决定是否为 map）

2. 约束与校验#

• 字符串：minLength、maxLength、pattern、enum、format（如 date-time、uuid、email）。
• 数值：minimum、maximum、exclusiveMinimum、exclusiveMaximum、multipleOf。
• 数组：minItems、maxItems、uniqueItems。
• 对象：required、minProperties、maxProperties、additionalProperties（控制是否允许未声明字段，及其类型）。

示例：

1
type: object
2
required: [id, name]
3
properties:
4
  id:
5
    type: string
6
    format: uuid
7
  name:
8
    type: string
9
    minLength: 1
10
  labels:
11
    type: object
12
    additionalProperties:
13
      type: string

3. 组合与多态#

• oneOf: 多选一
• anyOf: 任一匹配
• allOf: 全部匹配（常用于“继承/扩展”）
• not: 排除

Go 中对 oneOf/anyOf 的表达策略：

• 手写自定义类型与 json.Unmarshaler 判别；
• 借助生成器的辅助类型；
• 通过 discriminator 明确区分字段，提高可生成性与可读性。

4. 可空、读写属性、弃用#

• OpenAPI 3.0：nullable: true；3.1 更推荐 type: ["string", "null"] 等联合类型写法。
• readOnly：仅响应体现，客户端提交可省略。
• writeOnly：仅请求体现，响应应省略。
• deprecated: true：标记弃用，但不影响校验。

5. 示例与默认值#

• example：单个示例。
• examples：命名示例集合。
• default：字段未提供时的默认值（规范层面的语义，具体是否生效依赖服务端实现与生成器支持）。

1. 验证与质量控制#

• 在 CI 中加入校验步骤：语法有效性、引用完整性、风格约束。

• 可以使用 Go 库（如 kin-openapi）在单测或启动时验证文档：

  1
  loader := openapi3.NewLoader()
  2
  doc, err := loader.LoadFromFile("openapi.yaml")
  3
  if err != nil { /* handle */ }
  4
  if err := doc.Validate(context.Background()); err != nil { /* handle */ }
  

2. 代码生成（服务端与客户端）#

两条常见线路：

• 轻量生成器（如 deepmap/oapi-codegen） 适合与 chi、gin 集成，能生成类型、服务接口、客户端、请求校验中间件。 典型做法：

  1. 用 OpenAPI 定义契约；
  2. 生成 Go 类型与服务接口；
  3. 你只需实现接口方法并挂载到路由；
  4. 可用生成的校验器在入站请求处做 schema 校验。

• OpenAPI Generator（多语言生态广，需 Java 运行时） 适合同时生成多语言客户端或服务器桩代码。

选择原则：以团队现有栈、生成代码质量、可维护性与工具链稳定性为首要考虑。

3. 路由绑定与校验#

• 生成器通常提供“把接口实现绑定到路由”的适配函数。
• 强烈建议在路由层启用“请求校验中间件”，确保落到业务逻辑之前已经满足 OpenAPI 的参数与 schema 约束。

4. 与 YAML 配置的关系#

• OpenAPI 文档本身是 YAML 文件；服务运行配置（端口、数据库）也是 YAML。二者解耦：

  • 配置 YAML → 用 yaml.v3/viper 加载到结构体；
  • OpenAPI YAML → 仅用于契约、校验与代码生成，不直接参与运行时配置。