Python 从零构建生产级服务的步骤

uvicorn 是 fastapi 生产部署的必需 asgi 服务器，必须显式安装并禁用 –reload；需用 pip-compile 生成带哈希的 requirements.txt；配置应通过 pydantic-settings 管理并注入敏感信息；日志须用 dictconfig 配置 json 格式输出至 stdout，/health 接口需探测真实依赖。

选对 Web 框架：FastAPI 不是唯一解，但 uvicorn 是绕不开的起点

生产级服务不是跑通 print("Hello World") 就算完事。python 里真正扛住并发、自带 OpenAPI、能无缝对接 CI/CD 的框架，FastAPI 确实省心，但它依赖 uvicorn（或 hypercorn）作为 ASGI 服务器——这点常被新手忽略，以为装了 fastapi 就自动“可上线”。

常见错误现象：uvicorn main:app 在本地跑得飞起，一上 docker 就报 Address already in use 或静默退出；或者用 python -m fastapi dev（不存在的命令）白忙活半天。

• 必须显式安装 uvicorn，且生产环境禁用 --reload 参数
• uvicorn 启动时加 --host 0.0.0.0，否则容器内无法被外部访问
• 别用 flask + gunicorn 混搭应付高 I/O 场景——WSGI 架构在大量异步数据库/http 调用下会卡死线程池

环境隔离与依赖固化：requirements.txt 必须带哈希，pip-tools 比 pip freeze 可靠

线上服务崩在 ImportError: cannot import name 'XXX' from 'YYY'，十次有八次是依赖版本漂移。直接 pip freeze > requirements.txt 会把本地开发工具（如 ipython、black）也塞进去，还漏掉间接依赖的精确版本。

使用场景：CI 流水线构建镜像、K8s Pod 启动前校验、回滚到某次发布版本。

立即学习“Python免费学习笔记（深入）”；

• 用 pip-compile（来自 pip-tools）生成带 --hash 的 requirements.txt
• pyproject.toml 里声明 [build-system] 和 [project]，避免 setup.py 这种过时写法
• Dockerfile 中用 copy requirements.txt . + RUN pip install --no-cache-dir -r requirements.txt，别把整个 src/ 目录 COPY 进去再 pip install

配置管理：别把 SECRET_KEY 写进代码，pydantic-settings 是目前最稳的解法

硬编码 SECRET_KEY = "dev-key" 或用 .env 文件但没校验类型，上线后要么 500 报错，要么 JWT 签名失效却查不出原因。

参数差异：os.getenv() 返回字符串，但数据库端口要 int；bool("False") 居然是 True——这些隐式转换在线上环境会咬人。

• 用 pydantic-settings 定义配置类，字段类型即校验规则，缺失必报错
• .env 文件只放非敏感值；SECRET_KEY、DB_PASSWORD 必须通过 K8s Secret 或云厂商参数仓库注入
• 别在配置类里写默认值如 database_url: str = "sqlite:///./test.db"——测试和生产共用一个模型，但默认值只该出现在测试配置中

日志与健康检查：Logging.config.dictConfig 配一次够用半年，/health 接口不能只 return {“status”: “ok”}

出问题时翻不到有效日志，或者监控系统反复告警 “服务不可用”，结果发现是 /health 接口没连 DB 就返回 200——这类低级失误在真实运维中高频出现。

性能影响：用 print() 或默认 root logger 输出，高并发下会阻塞主线程；不设 rotation 的文件日志可能撑爆磁盘。

• 用 dictConfig 配置 JSON 格式日志，输出到 stdout（容器日志采集器能自动解析）
• /health 接口必须做轻量级依赖探测：比如尝试 select 1 到主库，超时 2 秒就返回 503
• 禁止在日志里打印用户手机号、Token、完整 trace_id——用 redact 字段或日志中间件脱敏

真正的难点不在写代码，而在让每个环节都“可观察、可验证、可中断”。比如 uvicorn 的 --limit-concurrency 参数调多少，得看实际压测时的 P99 延迟，而不是抄网上的数字。这些细节不写进文档，但决定服务能不能活过第一个流量高峰。