5个打字文章高频坑点及最佳实践指南
刚学会Python语法就急着上手写项目？别慌。我见过太多人卡在“代码能跑但项目搭不起来”的环节。问题不在语法，而在你没掌握打字文章开发中的最佳实践。那些看似简单的代码片段，脱离框架就是空中楼阁。
坑一：环境隔离没做好
现象：本地能跑，部署就崩。依赖版本冲突，pip freeze 导出的列表里混着测试库和生产库。
根本原因：直接在系统Python环境装包。新手习惯用pip install一把梭，没建虚拟环境。结果A项目的requests 2.25和B项目的requests 2.31打架，部署时镜像构建失败。
正确写法对比：
错误写法（直接装包）：
# 在系统环境直接执行
pip install flask sqlalchemy
正确写法（使用venv）：
# 创建隔离环境
python -m venv .venv
source .venv/bin/activate # Linux/Mac
.venv\Scripts\activate # Windows# 安装依赖到隔离环境
pip install flask sqlalchemy
复现与修复：
删掉项目根目录的requirements.txt，重新生成。确保venv文件夹被.gitignore忽略。官方源码仓库里每个项目都提供pyproject.toml或setup.py，照着配依赖最稳。
规避建议：
- 永远在项目根目录建
.venv - 用
poetry或pipenv管理依赖，比纯pip省心 - CI/CD流水线里加一步“干净环境安装测试”
坑二：配置硬编码
现象：改个数据库密码要重新打包镜像。测试环境连生产库，删表事故频发。
根本原因：把DB_HOST = "192.168.1.100"写死在代码里。环境切换靠注释/取消注释，改错一行就全崩。
正确写法对比：
错误写法（硬编码）：
# config.py
DB_HOST = "prod-db.internal"
DB_PASSWORD = "hardcoded123"
正确写法（环境变量）：
# config.py
import osclass Config:DB_HOST = os.getenv("DB_HOST", "localhost")DB_PASSWORD = os.getenv("DB_PASSWORD")DEBUG = os.getenv("FLASK_DEBUG", "false").lower() == "true"
复现与修复：
把代码里所有IP、密码、密钥抽到.env文件（别提交到Git）。用python-dotenv加载：
from dotenv import load_dotenv
load_dotenv()
规避建议：
- 生产配置走K8s Secret或Vault，别放
.env - 代码里加校验：启动时检查必填环境变量是否存在，缺了直接报错退出
- 参考Flask官方文档的“Configuration”章节，那里讲了怎么分层覆盖配置
坑三：数据库迁移没版本控制
现象：加个字段，线上跑着跑着报Unknown column。回滚时手动ALTER TABLE，删错列。
根本原因：直接连库执行ALTER TABLE。没有迁移脚本，没人知道当前库结构对应哪次代码变更。
正确写法对比：
错误写法（手动改表）：
-- 直接在Navicat里执行
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
正确写法（Alembic迁移）：
# alembic/versions/001_add_phone.py
def upgrade():op.add_column('users', sa.Column('phone', sa.String(20), nullable=True))def downgrade():op.drop_column('users', 'phone')
复现与修复：
项目里集成Alembic（SQLAlchemy官方迁移工具）。每次改模型，跑alembic revision --autogenerate生成迁移脚本，review后合并。部署时跑alembic upgrade head。
规避建议：
- 迁移脚本必须可逆（写
downgrade） - 大表加字段分两步：先加
NULL列，再回填数据，最后改NOT NULL - 迁移脚本进Git，和代码一起review
坑四：日志只打print
现象：线上报错，翻容器日志找半天。日志格式不统一，没法grep。错误堆栈被截断。
根本原因：用print()调试，没接logging模块。生产环境不知道开哪个级别，全打或全关。
正确写法对比：
错误写法（print调试）：
print(f"User {user.id} logged in")
print("Error:", e)
正确写法（logging模块）：
import logginglogger = logging.getLogger(__name__)try:user = login(username, password)logger.info("User login successful", extra={"user_id": user.id})
except Exception as e:logger.exception("Login failed") # 自动带堆栈raise
复现与修复： 统一日志配置。Flask应用启动时：
app.logger.setLevel(logging.INFO)
handler = logging.FileHandler("app.log")
formatter = logging.Formatter('%(asctime)s %(levelname)s %(name)s - %(message)s'
)
handler.setFormatter(formatter)
app.logger.addHandler(handler)
规避建议：
- 禁止
print进生产代码，lint规则里加no-print - 日志加trace_id，请求链路能串起来
- 错误日志必须带完整堆栈，用
logger.exception而不是logger.error(str(e))
坑五：没有健康检查端点
现象：K8s把没准备好的Pod标记为Ready，流量打进来全502。重启后服务没起来，但探针显示健康。
根本原因：没写/healthz和/readyz端点。K8s探针配置错误，或者探针逻辑太简单（只返回200）。
正确写法对比：
错误写法（空探针）：
@app.route("/healthz")
def healthz():return "ok", 200
正确写法（深度检查）：
@app.route("/healthz")
def healthz():# 检查数据库连接try:db.session.execute(text("SELECT 1"))except Exception:return "db down", 503return "ok", 200@app.route("/readyz")
def readyz():# 检查外部依赖（Redis、MQ等）if not redis_client.ping():return "redis not ready", 503return "ready", 200
复现与修复： K8s YAML里配置：
livenessProbe:httpGet:path: /healthzport: 8080initialDelaySeconds: 10
readinessProbe:httpGet:path: /readyzport: 8080initialDelaySeconds: 5
规避建议：
/healthz只查自身存活，/readyz查依赖就绪- 探针超时设短点（3-5秒），别等依赖慢慢连
- 依赖故障时返回503，K8s会自动摘流量，等恢复后再放回来
这些坑我踩过，团队里新人也踩过。语法书不会教你这些，但每个项目都会撞。记住：能跑的代码不等于能上线的代码。环境隔离、配置管理、数据库迁移、日志规范、健康检查，这五件事做到位，项目搭建成功率能提升80%。
官方源码仓库里那些成熟项目（比如Flask、Django、FastAPI）的代码结构，值得逐行看。别只抄片段，看他们怎么组织配置、怎么管依赖、怎么打日志。
还有什么不懂的？评论区留言挨个回。
