健康检查接口应返回包含status、db_connected、db_ping_time_ms和error字段的结构体，其中status为"ok"或"error"，db_connected为布尔值，db_ping_time_ms为毫秒级延迟，error仅在出错时存在且为字符串；须使用pymongo.mongoclient的admin.command("ping")配合serverselectiontimeoutms=2000和sockettimeoutms=2000实现轻量探测，并复用全局client实例以避免连接数爆炸。
健康检查接口该返回什么字段？
服务健康检查不是只返回 200 OK 就够了。MongoDB 连通性必须可验证，且结果要能区分「服务启动但 DB 不可用」和「DB 可用但查询失败」两类问题。建议返回结构体包含 status（"ok" 或 "error"）、db_connected（布尔）、db_ping_time_ms（毫秒级延迟）、error（仅出错时存在，值为字符串）。
用 pymongo.MongoClient 的 admin.command("ping") 而非 server_info()
server_info() 在连接池未建立时可能阻塞或抛异常，而 admin.command("ping") 是轻量、有超时控制的标准探测方式。关键点：
- 必须指定
serverSelectionTimeoutMS=2000和socketTimeoutMS=2000，否则默认无超时，健康检查会卡住 - 调用前不需显式
client.admin.command("ping")，直接执行即可；但必须捕获pymongo.errors.ConnectionFailure、pymongo.errors.ServerSelectionTimeoutError和pymongo.errors.OperationFailure - 避免在每次请求中新建
MongoClient实例——复用全局 client，否则连接数爆炸
FastAPI / Flask 中实现时如何避免阻塞主线程？
Python Web 框架默认是同步的，admin.command("ping") 是同步 I/O。若没设好超时，一个坏 MongoDB 就会让整个健康端点 hang 住。实操要点：
- FastAPI：用
async def无意义，pymongo本身不支持 async；应确保 client 初始化时已传入超时参数，并在路由函数里做 try/except 包裹 - Flask：同理，不要用
threading手动开线程——增加复杂度且难管控；靠 client 级超时 + 请求级 timeout 更可靠 - 如果用了 Gunicorn，注意
--timeout值必须 > MongoDB ping 超时（如设 client 为 2s，则 gunicorn timeout 至少 5s），否则 worker 被杀导致误报
容器化部署时为什么健康检查总失败？
Kubernetes livenessProbe 或 Docker HEALTHCHECK 命令失败，常见原因不是代码逻辑错，而是环境配置脱节：
- MongoDB 地址写死为
localhost:27017—— 容器内 localhost 是自身，不是宿主机或另一容器；必须用 service 名（如mongodb:27017）并确认网络策略放行 - 未配置认证：测试环境可能关 auth，但生产开启了；健康检查请求必须带
username/password参数初始化 client，或使用带凭证的 connection string - Docker HEALTHCHECK 默认间隔太短（如 30s），而首次连接 MongoDB 可能因 DNS 解析+TCP 握手+auth 耗时接近 5s；建议设
start_period=60s，避免启动期误杀
真正麻烦的不是连不上 MongoDB，而是连上了却因权限不足、副本集配置漂移、或 TLS 证书不匹配导致 ping 返回 OperationFailure。这类错误不会触发连接异常，但会使健康状态为 false——得在 error 字段里明确吐出原始异常 message，不然排查时只能盲猜。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
