我的 AI 代码清理方法论：从原型到生产，只需 5 步

AI 生成代码的速度很快，快到常常让人产生一种错觉： "看起来能跑，就差不多可以用了。"

但真正进入项目以后，问题往往也来得很快：异常处理不完整、输入校验缺失、业务逻辑直接堆在路由里、领域对象和 API schema 混用、测试覆盖不足......这些并不是偶发情况，而几乎是 AI 代码的"标准附带品"。

所以，在真正把 AI 生成的代码放进生产环境之前，我通常会走一套固定的清理流程。它的目标不是"把代码修得更好看"，而是把一段能演示的原型，整理成一段可维护、可测试、可上线 的工程代码。

这套流程，我已经在多个项目中反复使用。今天把它整理出来，供你参考。

为什么需要一套固定流程

如果你第一次审查 AI 生成的代码，大概率能一眼看出很多问题；第二次审查时，你会发现问题开始变多，因为第一轮你没看到的细节正在慢慢浮现；到了第三次，若项目又赶进度，人就容易动摇："其实也还能用吧？"

这正是固定 playbook 的意义。

它不是为了限制开发者，而是为了减少人为状态对代码质量的影响。因为人在疲劳、赶工、认知负担较重时，很容易对"看起来没问题"的代码放松警惕。飞行员会使用检查单，不是因为他们不专业，而是因为他们足够专业，知道流程比直觉更可靠。

相关经验也反复证明了这一点。很多团队在使用 Copilot 或其他代码生成工具后，确实能提升编写速度，但后续也常伴随着更多细节问题，比如边界条件遗漏、类型不严谨、测试不足、错误处理松散。AI 生成代码最常见的问题之一，不是"完全不能用"，而是"看起来正确，实际上不正确"。后续验证和修复所消耗的时间，往往会抵消一部分甚至大部分效率收益。

第一步：先看架构，不要急着改细节

AI 生成代码最常见的问题，不是语法错误，而是结构不对。它往往能把功能拼出来，但不一定符合你现有系统的分层方式。

所以我会先问几个基础问题：

• 代码是否放在正确的层？
• 路由层、服务层、数据访问层的职责是否清晰？
• API 层有没有把 Pydantic 模型和 ORM 模型混在一起？
• 包结构是否符合项目规范？
• 命名风格是否与现有代码库保持一致？

一个很典型的问题：所有逻辑都挤在路由里

AI 很喜欢把验证、业务规则、数据库操作写在同一个函数里。短期看，这样确实"省事"；长期看，这种写法几乎一定会变成维护负担。

修改前：路由函数里塞满所有逻辑

from fastapi import APIRouter, HTTPException, Request
from datetime import datetime

router = APIRouter()

@router.post("/orders")
def create_order(request: Request):
    data = request.json()

    if not data.get("items"):
        raise HTTPException(status_code=400, detail="No items")

    total = 0
    for item in data["items"]:
        total += item["price"] * item["quantity"]

    order = {
        "items": data["items"],
        "total": total,
        "status": "CREATED",
        "created_at": datetime.utcnow(),
    }

    # 假装这里直接写数据库
    return order

这段代码的问题很明显： 接口层、业务层、持久化层全混在了一起。

修改后：按职责拆分

from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
from datetime import datetime
from sqlalchemy.orm import Session

router = APIRouter()


class CreateOrderItem(BaseModel):
    product_id: str
    quantity: int = Field(gt=0)
    price: float = Field(gt=0)


class CreateOrderRequest(BaseModel):
    items: list[CreateOrderItem]


class OrderService:
    def __init__(self, session: Session):
        self.session = session

    def create_order(self, request: CreateOrderRequest):
        if not request.items:
            raise ValueError("No items")

        total = sum(item.price * item.quantity for item in request.items)

        order = Order(
            total=total,
            status="CREATED",
            created_at=datetime.utcnow(),
        )
        self.session.add(order)
        self.session.commit()
        self.session.refresh(order)
        return order


@router.post("/api/orders", status_code=201)
def create_order(
    request: CreateOrderRequest,
    service: OrderService = Depends(get_order_service),
):
    order = service.create_order(request)
    return OrderResponse.from_orm(order)

这样拆开以后，好处非常直接：

业务逻辑可以脱离 HTTP 层单独测试，接口调整也不会牵一发动全身。更重要的是，后面如果要扩展订单状态、增加风控校验或引入事件发布，代码结构仍然扛得住。

第二步：安全加固，别让"能用"变成"有风险"

AI 生成代码在安全方面经常比较"天真"。它默认世界是友好的，但真实环境显然不是。

因此，输入和输出一定要单独审查。

输入侧：不要直接接收 ORM 模型

常见问题

@router.post("/users")
def create_user(user: User):
    db.add(user)
    db.commit()
    return user

这种写法的问题在于，外部请求和内部实体直接绑定。

一旦字段设计稍有变化，或者外部传入了不该写入的字段，就容易出问题。

更稳妥的做法：使用请求模型

from pydantic import BaseModel, EmailStr, Field

class CreateUserRequest(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    email: EmailStr
    bio: str | None = Field(default=None, max_length=500)

这样做的好处是：

• 外部输入和内部模型解耦
• 可以明确约束字段长度、格式和必填项
• 后续扩展字段时，不容易影响已有逻辑

输出侧：不要直接返回 ORM 对象

很多人会忽略这一点，但它同样重要。 如果直接返回 ORM 对象，数据库中的内部字段可能会被一并暴露出去，比如password_hash、internal_notes 之类的内容。

更合理的做法：使用响应模型

from pydantic import BaseModel

class UserResponse(BaseModel):
    id: int
    name: str
    email: str
    bio: str | None = None

    class Config:
        from_attributes = True

建议检查项

• 是否使用请求模型，而不是直接使用 ORM 模型？
• 是否启用了参数校验？
• 是否通过响应模型控制输出字段？
• 是否存在 SQL 注入风险？
• 是否有权限校验？
• 日志里有没有打印敏感信息？
• 对外接口有没有必要的限流措施？

可以记住一句非常实用的原则：

所有进入系统的数据都不应默认可信，所有输出给外部的数据都应默认可见。

这个原则虽然简单，但在代码评审时非常管用。

第三步：错误处理要统一，不要让异常"自由发挥"

高质量代码的一个标志，是它在出错时依然表现稳定。 而 AI 生成代码最容易出的问题之一，就是异常处理不统一：有的地方直接raise Exception，有的地方返回空值，有的地方打印日志后悄悄吞掉错误。

这会让系统非常难维护。

我通常采用三层错误处理方式

第一层：领域异常

class BusinessError(Exception):
    def __init__(self, message: str, code: str = "BUSINESS_ERROR"):
        super().__init__(message)
        self.code = code


class InsufficientStockError(BusinessError):
    def __init__(self, product_id: str, requested: int, available: int):
        super().__init__(
            f"Product {product_id}: {requested} requested, only {available} available",
            code="INSUFFICIENT_STOCK",
        )

这类异常的重点是：用业务语言表达问题，而不是直接关心 HTTP 返回码。

第二层：全局异常处理器

如果是 FastAPI，可以这样做：

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from datetime import datetime

app = FastAPI()


@app.exception_handler(BusinessError)
async def handle_business_error(request: Request, exc: BusinessError):
    return JSONResponse(
        status_code=422,
        content={
            "status": 422,
            "message": str(exc),
            "code": exc.code,
            "timestamp": datetime.utcnow().isoformat(),
        },
    )


@app.exception_handler(KeyError)
async def handle_not_found(request: Request, exc: KeyError):
    return JSONResponse(
        status_code=404,
        content={
            "status": 404,
            "message": "Resource not found",
            "code": "NOT_FOUND",
            "timestamp": datetime.utcnow().isoformat(),
        },
    )


@app.exception_handler(Exception)
async def handle_unexpected(request: Request, exc: Exception):
    # 这里应该接入日志系统
    return JSONResponse(
        status_code=500,
        content={
            "status": 500,
            "message": "An internal error occurred",
            "code": "INTERNAL_ERROR",
            "timestamp": datetime.utcnow().isoformat(),
        },
    )

这一层负责把内部异常转换成统一的 HTTP 响应。

第三层：统一错误返回格式

from pydantic import BaseModel
from datetime import datetime

class ErrorResponse(BaseModel):
    status: int
    message: str
    code: str
    timestamp: datetime

为什么这套方式有效

因为它将三种关注点分开了：

• 领域异常：描述业务问题
• 异常处理器：负责协议转换
• 错误响应：负责客户端消费体验

这样一来，前端、网关或其他调用方收到的错误格式始终一致，系统也更容易排查和演进。

第四步：测试不是"可选项"，而是收尾动作的一部分

AI 生成的代码通常不会自动附带足够的测试。

但没有测试的代码，即使当前能跑，也很难说是稳的。

我一般会要求每个功能至少补齐以下几类测试：

• 正常路径测试：主流程是否能正确完成
• 失败路径测试：异常条件是否处理得当
• 边界条件测试：空值、空集合、极值是否稳定
• 集成测试：接口到服务的完整链路是否可用

服务层测试示例

from unittest.mock import Mock

def test_create_order_calculates_total():
    request = CreateOrderRequest(
        items=[
            CreateOrderItem(product_id="PROD-1", quantity=2, price=29.99),
            CreateOrderItem(product_id="PROD-2", quantity=1, price=49.99),
        ]
    )

    session = Mock()
    service = OrderService(session)

    result = service.create_order(request)

    assert result.total == 109.97

接口层集成测试示例

from fastapi.testclient import TestClient

client = TestClient(app)

def test_full_order_flow_returns_201(mocker):
    mock_service = mocker.patch("path.to.module.get_order_service")
    mock_service.return_value.create_order.return_value = test_order_response()

    response = client.post(
        "/api/orders",
        json={
            "items": [
                {"product_id": "PROD-1", "quantity": 2, "price": 29.99},
                {"product_id": "PROD-2", "quantity": 1, "price": 49.99},
            ]
        },
    )

    assert response.status_code == 201
    assert "location" in response.headers
    assert response.json()["total"] == 109.97
    assert response.json()["status"] == "CREATED"

一个经验判断

如果一个功能只覆盖了"正常情况"，却没有覆盖异常路径和边界条件，那测试通常是不够的。

测试的目的不只是证明"它能跑"，更是证明"它在出问题时也不会乱跑"。

第五步：把质量要求放进 CI/CD，而不是靠人工记忆

很多团队的问题不是没有规范，而是规范只存在于脑子里。

但人的记忆并不适合长期承担质量控制这种工作，尤其是在需求密集、节奏紧张的项目里。

所以，最后一步是把这些要求放进 CI/CD 流水线里，让系统替你做检查。

一个基础流水线可以这样设计

stages:
  - lint
  - test
  - security
  - build

lint:
  script:
    - ruff check .
    - black --check .
    - mypy .

test:
  script:
    - pytest
    - pytest tests/integration

security:
  script:
    - bandit -r .
    - pip-audit

build:
  script:
    - python -m build
  only:
    - main

对 AI 代码建议增加的检查

• 是否引入了无用的依赖
• 是否出现重复逻辑
• 是否存在未使用的 import
• Python 版本是否与项目一致
• 是否破坏了原有的构建规范
• 是否通过了类型检查
• 是否有格式化和 lint 问题

CI/CD 的价值就在这里：它不是在"最后抓人"，而是在"过程里拦截问题"。

一份可以直接使用的检查清单

如果你希望把这套方法固定下来，可以直接把下面这份清单放进代码评审流程里：

AI 代码清理清单 架构审查

□ 分层是否正确？

□ 是否使用 Pydantic 模型而非 ORM 模型暴露接口？

□ 包结构是否一致？

□ 是否复用了现有项目模式？

□ 是否有输入校验？

安全加固

□ 是否通过响应模型控制输出？

□ 是否存在 SQL 注入风险？

□ 是否做了权限校验？

□ 日志是否泄露敏感信息？

错误处理

□ 是否定义了领域异常？

□ 是否有全局异常处理？

□ 是否返回统一错误格式？

□ 是否避免未处理异常？

测试策略

□ 是否覆盖正常路径？

□ 是否覆盖失败路径？

□ 是否覆盖边界条件？

□ 是否至少有一个集成测试？

CI/CD 集成

□ 是否自动格式化检查？

□ 是否把测试纳入流水线？

□ 是否做了依赖安全扫描？

□ 是否清理了无用依赖？

结语：AI 只是起点，流程才决定上限

AI 正在改变开发方式，但它并不会自动替你解决工程问题。

它更像一个高产但不够谨慎的初级 开发者：能快速产出，但往往需要强约束、强审查和强测试来把结果拉回生产标准。

所以，真正重要的不是"AI 写了多少代码"，而是你有没有一套稳定的方法，把这些代码变成可维护、可交付的系统资产。

从这个角度看，代码清理不是额外成本，而是工程化的一部分。甚至可以说，流程本身，就是产品质量的一部分。