JSON/YAML 转换：Kubernetes 与 Docker Compose 的语义保留

一、问题概述：格式合法不代表平台语义正确

一个对象可以被无损地 JSON.stringify 或 YAML 序列化，但 Kubernetes 还需要 apiVersion、kind、metadata、spec 等结构；Compose 则以 services 及其服务配置为核心。转换器只负责值和容器形状，不能替平台补全或验证所有字段。

二、最小复现：两个平台的根结构不同

下面只展示经过解析的 JSON 对象形状。字段是否完整、版本是否支持，仍应交给目标平台的 schema 或命令行验证。

const kubernetes = {
  apiVersion: "apps/v1",
  kind: "Deployment",
  metadata: { name: "web" },
  spec: { replicas: 2 },
};
const compose = {
  services: { web: { image: "example/web", ports: ["8080:80"] } },
};
console.log(Object.keys(kubernetes)); // apiVersion, kind, metadata, spec
console.log(Object.keys(compose)); // services

三、根因：同名概念在两个 schema 中不等价

Kubernetes 的资源对象、容器列表、label 和 resource quantity 有自己的类型约束；Compose 的 service、volume、network、environment 和 ports 也有独立约定。把 ports、环境变量或副本数按字段名机械复制，可能保留文本却改变平台含义。

四、推荐方案：先选择目标平台，再做语义校验

JSON↔YAML 转换应保持对象、数组、字符串、数字、布尔和 null 的值；平台适配另做 schema 映射。Kubernetes 与 Compose 使用不同的验证流程和版本文档，不能共用一套“自动修正”规则。对 ports、environment、labels 等高歧义字段，先确认目标 schema 的允许形状。

五、完整代码：按目标平台检查最小根结构

以下函数只做早期分类，避免把 Kubernetes 对象误交给 Compose 流程，或反过来。它不生成完整部署清单，也不假装执行平台校验。

type Target = "kubernetes" | "compose";

function assertRootShape(value: unknown, target: Target): void {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("document must be an object");
  const record = value as Record<string, unknown>;
  if (target === "kubernetes" && (typeof record.apiVersion !== "string" || typeof record.kind !== "string" || !record.metadata)) {
    throw new Error("Kubernetes resource needs apiVersion, kind, and metadata");
  }
  if (target === "compose" && (!record.services || typeof record.services !== "object")) {
    throw new Error("Compose document needs services");
  }
}

assertRootShape({ apiVersion: "v1", kind: "ConfigMap", metadata: { name: "cfg" } }, "kubernetes");
assertRootShape({ services: {} }, "compose");

六、常见错误方案

把 Kubernetes 的 metadata.labels 当成 Compose 的任意标签字典、把 Compose 的 ports: ["8080:80"] 改成 Kubernetes Service 端口对象，或把 environment 的列表/映射形式随意互换，都可能在格式仍合法时改变语义。只改缩进和引号不能修复这种差异。

七、边界条件：字符串、数字、环境变量与敏感值

YAML 解析器可能对无引号标量做类型解析，生成配置时应对环境变量、镜像标签、资源数量和端口文本确认是否需要引号。Secret、密码和 token 不应为了转换而写入示例或日志；平台 schema 也不等于敏感数据脱敏策略。

八、如何验证语义保留

先做 JSON/YAML 往返比较，检查对象键、数组顺序、null 和标量类型；再分别使用 Kubernetes 或 Compose 的目标 schema/验证命令检查字段。对 ports、environment、labels、volumes 和资源字段写针对性断言，不能只看 YAML 是否能被解析。

九、FAQ

问：JSON 转 YAML 后就能直接 kubectl/Compose 使用吗？答：不一定，仍需匹配目标平台 schema、版本和字段约定。

问：Kubernetes 和 Compose 能共用一套转换模板吗？答：只能共用基础数据序列化，平台语义映射必须分开。

问：为什么同一个数字有时要写成字符串？答：环境变量、端口或资源数量的 schema 可能要求字符串，必须以目标文档为准。

十、总结

JSON↔YAML 只解决表示层，Kubernetes 与 Docker Compose 还需要各自的 schema 语义。先固定目标平台，保留基础值类型，再对根结构、ports、environment、labels 和资源字段分别验证，避免把格式转换误当成部署配置转换。