结论：用 go 接 azure cosmos db 应弃用官方 azure-cosmos-go sdk（仅支持 nosql api、维护滞后、多活能力残缺），改用 mongodb driver 连接其 mongodb api——这是当前最稳定、文档最全、社区验证充分且真正支持全球多活读写的路径。
直接说结论：用 Go 接 Azure Cosmos DB，别碰官方 azure-cosmos-go SDK（它只支持 NoSQL API 且维护滞后），改用 MongoDB Driver 连接 Cosmos DB 的 MongoDB API —— 这是当前最稳、文档最全、社区反馈最多、且能真正跑通全球多活读写的路径。
为什么不用官方 Go SDK？
官方 azure-cosmos-go SDK 目前（截至 2026 年 6 月）仅支持 NoSQL API，不支持 MongoDB API 或 Cassandra API。更关键的是，它的错误处理抽象层太重，error 类型嵌套深，StatusCode 常被吞掉，调试时连 429 Too Many Requests 都得扒源码才能定位；同时对 PreferredLocations 区域优先级、多活写冲突消解、SessionToken 透传等核心多活能力支持残缺。真实线上踩过坑的团队反馈：用它连东京+法兰克福双活，读请求随机 fallback 到远端区域，P99 延迟翻倍。
用 MongoDB Driver 连 Cosmos DB 的实操要点
这是微软官方推荐的替代路径（见 Azure 文档 “Quickstart: Use Go with MongoDB driver for Azure Cosmos DB”），本质是把 Cosmos DB 当作兼容 MongoDB 协议的“云上副本”，所有操作走标准 wire protocol。
- 连接字符串必须带
replicaSet=globaldb和ssl=true，否则无法启用多活路由：mongodb://<user>:<pass>@<account>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@<account></account></account></pass></user> -
ClientOptions中必须显式设置ReadPreference，否则默认走 primary，丧失就近读能力：options.SetReadPreference(readpref.Nearest()) - 若需强一致读（比如库存扣减后立即查余额），不能只靠
readConcern，还得在写操作后手动提取并传递session.Token()到后续读请求中 —— Cosmos DB 的majority一致性模型依赖这个 token 做跨区域同步确认 - 务必关闭
socketKeepAlive的默认心跳（Cosmos DB 不响应 ping），否则连接池会频繁断连重连：options.SetSocketKeepAlive(false)
分区键（Partition Key）设计直接影响全球扩展性
Cosmos DB 的 Partition Key 不是“选个字段就行”，而是你全球流量拓扑的锚点。选错会导致跨区域请求暴涨、RU 消耗失控、甚至写冲突。
- 绝对不要用全局唯一 ID（如
uuid或ObjectId）做Partition Key—— 这会让写请求随机打散到所有物理分片，失去 locality，跨区域协调开销激增 - 优先选业务天然聚合维度：比如电商订单系统用
tenantId+regionCode组合（如"jp-tokyo"），确保同一租户+区域的数据落在同一逻辑分区，本地读写闭环 - 如果必须按用户 ID 分片，至少加一层哈希桶（如
userId % 64），避免单个热点用户打爆单一分区 - 注意：MongoDB Driver 写入时，
Partition Key字段必须显式出现在 document 中，且值不能为null；否则 Cosmos DB 会拒收并返回模糊的BadRequest错误，日志里只显示"PartitionKeyExtractorError"
Global Write + Local Read 的真实延迟表现
很多人以为开了多活就自动低延迟 —— 实际不是。Cosmos DB 的延迟取决于你如何调度读写，而不是单纯开了几个区域。
- 写永远发往
WriteRegion（控制台里设的“写入区域”），哪怕你在东京发起请求，SDK 也会自动重定向到法兰克福写入 —— 这是强一致性保障的代价 - 读默认走
Nearest()，但“最近”是 DNS + SDK 缓存决定的，不是实时网络测速。如果你服务部署在东京，但 SDK 初始化时PreferredLocations没填Japan East，它可能从新加坡读，延迟从 15ms 拉到 80ms - 真正要压到 P99 X-Forwarded-For，后端解析 IP 归属地，动态生成
ClientOptions并复用连接池 —— 否则一个mongo.Client实例无法适配多地域流量
最容易被忽略的一点：Cosmos DB 的 RU/s 是按区域独立配置的，但 Partition Key 设计不当导致跨区域请求增多时，每个区域的 RU 消耗都会飙升，账单可能翻倍而不自知。上线前务必用真实流量压测各区域 RU 使用率，别只看总览页的平均值。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
