# 兼容性

[English](../COMPATIBILITY.md) | [简体中文](COMPATIBILITY.md)

本矩阵只描述当前实现和自动化测试已覆盖的行为。

- **支持**：已经实现并测试；
- **部分支持**：仅支持“边界”列出的子集；
- **不支持**：生成前产生诊断，或 warning 后明确忽略。

## 文档、引用与合并

| 能力 | 状态 | 边界 |
|---|---|---|
| OpenAPI 3.0.x / 3.1.x | 支持 | JSON/YAML；客户端生成所需常见 Schema Object 子集 |
| Swagger/OpenAPI 2.0 | 不支持 | `openapi.unsupported_version` error |
| 本地 `$ref` | 支持 | 各 component 分组的 JSON Pointer |
| 相对文件 / file URL `$ref` | 支持 | 相对当前引用文档解析 |
| HTTP(S) `$ref` | 支持 | 单次运行缓存、依赖追踪和循环诊断 |
| 外部 component 重名 | 支持 | 确定性改名并 warning |
| 多 root source | 支持 | 确定性 merge；component/operation 冲突诊断 |
| unresolved `$ref` | 支持诊断 | error，不静默转换成 `dynamic` |
| callbacks / webhooks | 不支持 | warning，不生成反向调用 client |
| Link Object | 不支持 | `openapi.links_not_supported` warning |

当前不是完整 JSON Schema 2020-12 实现。`$defs` 作为生成根、
`if`/`then`/`else`、`not`、`contains`、`dependentSchemas` 和 unevaluated
property/item 语义不在当前契约中。

## Schema 与 model

| 能力 | 状态 | 边界 |
|---|---|---|
| object / array / map | 支持 | 递归容器和 inline schema |
| `properties` + `additionalProperties` | 支持 | extra entry 在 JSON 根 round trip |
| string/number/integer/bool/date/date-time | 支持 | format 可由 type mapping 覆盖 |
| enum | 支持 | string、number、boolean wire value；inline/component |
| enum 成员名映射 | 支持 | 配置及常见 `x-enum` extension |
| enum unknown fallback | 支持 | 可配置 `JsonKey.unknownEnumValue` 输出 |
| required / nullable / absent | 支持 | 反序列化区分缺失和不允许 null；普通 Freezed 字段不保留 presence 历史 |
| readOnly / writeOnly | 支持 | 必要时生成 request/response directional variant |
| `allOf` | 支持 | 合并 object property、required 和 additional property |
| discriminator `oneOf`/`anyOf` | 支持 | local 或已归一化 object branch |
| 无 discriminator `oneOf`/`anyOf` | 部分支持 | primitive/container/object；重叠 `oneOf` 匹配会拒绝 |
| custom schema/type/format | 支持 | external import；宿主代码负责 JSON 转换契约 |
| constraint metadata | 部分支持 | 保留 description/doc comment；不生成 runtime validator |
| presence/dirty tracking | 不支持 | 无 Kiota 风格 backing store |

## HTTP wire 语义

| 能力 | 状态 | 边界 |
|---|---|---|
| path/query/header/cookie parameter | 支持 | type、required/default 和 wire name |
| matrix / label / simple | 支持 | 校验 location/style 组合 |
| form / spaceDelimited / pipeDelimited / deepObject | 支持 | 校验 query/cookie 组合 |
| explode / `allowReserved` | 支持 | Retrofit 无法表达时生成 transport adapter |
| Parameter Object `content` | 部分支持 | 必须恰有一个 media type |
| JSON / `+json` request body | 支持 | required body 和 null-to-absent |
| text request body | 支持 | typed `@Body` |
| `multipart/form-data` | 支持 | binary、primitive、array 和 structured JSON part |
| `application/x-www-form-urlencoded` | 支持 | typed field；复杂 encoding 使用 adapter |
| binary upload | 支持 | `Uint8List` |
| binary download | 支持 | `Uint8List` 或 Dio `ResponseBody` stream |
| XML / Protobuf / 任意 custom codec | 不支持 | content-type error，不生成不安全 decoder |

## Response、server 与 security

| 能力 | 状态 | 边界 |
|---|---|---|
| 多个 2xx / 204 / `2XX` | 支持 | 确定性 primary response；不同 JSON type 可 warning 后变成 `Object?` |
| `default` / 4xx / 5xx | 支持 | 保留 error model/IR metadata；不作为 success |
| response header | 支持 | status、type、required flag 和 description |
| raw response metadata | 支持 | `response_mode: http_response` |
| binary + JSON 混合 success media | 支持诊断 | 单个 Retrofit 方法无法安全 decode 时 error |
| root/path/operation server | 支持 | server variable default/enum 校验；preferred server 成为 client default |
| 多 server runtime 切换 | 部分支持 | 保留 metadata；不生成环境选择 UI |
| API key / Bearer / Basic | 支持 metadata | 生成 scheme/operation requirement；凭证由宿主 interceptor/provider 提供 |
| OAuth2 / OpenID / mutual TLS | 部分支持 | 仅 scheme/scope metadata；不生成完整授权流程 |
| security OR/AND requirement | 支持 | list 项是 OR；同一 map 项中的 scheme 是 AND |

## 生成与生命周期

| 能力 | 状态 | 边界 |
|---|---|---|
| Retrofit + Freezed | 支持 | 当前版本唯一完整 renderer |
| passthrough / external generic wrapper | 支持 | 可配置标准 envelope 检测 |
| model/property/parameter/operation mapping | 支持 | collision 校验和安全 identifier |
| schema/type/import mapping | 支持 | 递归 Dart `List`/`Map` type expression |
| tag/path/operation/model filter | 支持 | exact、glob 和 `regex:` |
| dry-run | 支持 | 报告 would-write/would-delete |
| Dart fix / format | 支持 | 仅本轮改变的主生成文件 |
| build_runner build/watch | 支持 | 在配置的宿主项目目录执行 |
| unchanged skip | 支持 | spec/config/content 和实际文件 SHA-256 |
| stale cleanup | 支持 | manifest ownership、root containment、用户修改保护 |
| concurrent generation lock | 支持 | manifest 旁的操作系统 exclusive lock |
| external template / plugin renderer | 不支持 | IR/preset 已分层，但无公开 renderer SPI |
| 完整 SDK package scaffold | 不支持 | 在已有项目内生成 API/model |

## 验证覆盖

仓库测试覆盖：

- parser、IR、renderer 和 lifecycle 阶段；
- OpenAPI 3.0 YAML、OpenAPI 3.1 JSON/FastAPI fixture；
- enum/命名 mapping、parameter wire style、response、schema 语义、security
  和 external/cyclic ref；
- reviewed SHA-256 golden；
- 生成到临时 Dart package，随后运行 build_runner、analysis 和 runtime test。

矩阵中的“支持”不代表超出所列边界的完整 OpenAPI/JSON Schema conformance。
引入新的 schema corpus 时，应先用最小 fixture 和 dry-run 验证。

诊断含义和处理方式见[诊断参考](DIAGNOSTICS.md)。