如何在AWS DocumentDB中存储含特殊键的OpenAPI文档？

AWS DocumentDB虽兼容MongoDB，但有明确约束：文档键名不能包含.或$，这是导致保存失败的核心原因（标准MongoDB允许这类键名，只是官方不推荐）。针对该问题，按优先级推荐以下方案：

1. 键名占位符替换（首选） #

存储前将键名中的.替换为唯一且无冲突的占位符（比如__DOT__，避免用下划线，防止原键自带下划线导致混淆），读取文档时再将占位符替换回.。

示例操作： #

• 存储转换：
  原键：application/vnd.hedtech.integration.v1.0.0+json
  转换后：application__DOT__vnd__DOT__hedtech__DOT__integration__DOT__v1__DOT__0__DOT__0+json
• 读取还原：把所有__DOT__替换回.即可。

优势： #

• 对现有代码改动极小，仅需在存储/读取环节添加一层转换逻辑
• 完整保留OpenAPI文档的原始结构，无元数据丢失
• 实现成本低，无需重构数据模型

2. 重构数据结构（适合新系统设计） #

如果是从头搭建存储方案，可调整content字段的结构，将原键值对形式改为数组对象，从根源规避特殊字符键名问题。

示例重构后的结构： #

"content": [
    {
        "mediaType": "application/vnd.hedtech.integration.v1.0.0+json",
        "schema": {
            "$ref": "#/components/schemas/api-name.json"
        }
    }
]

优势： #

• 完全符合DocumentDB约束，无兼容性隐患
• 数据结构更清晰，后续查询、维护更友好

劣势： #

• 需要修改OpenAPI文档的解析、生成逻辑，改动范围大，更适合新系统而非已有系统迁移

补充说明 #

标准MongoDB允许键名包含.，但官方不推荐——因为.在MongoDB查询语法中代表嵌套字段访问，可能引发后续查询逻辑错误。DocumentDB直接禁止这类键名，属于更严格的约束。

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