MonkeyCode 与 SDD：让 AI 写代码之前，先把规矩立好

@app.route("/api/user/<uid>", methods=["GET"])
def get_user(uid):
    user = db.query("SELECT * FROM users WHERE id=" + uid)
    return jsonify(user)

# .monkeycode/specs.yaml — 项目规范定义
version: "1.0"

architecture:
  layering:
    - name: controller
      allowed_deps: [service, dto]
      forbidden_deps: [repository]
    - name: service
      allowed_deps: [repository, dto]
    - name: repository
      allowed_deps: [model]

coding:
  error_handling:
    rule: must_use_custom_error
    custom_error_class: AppError
    no_bare_exceptions: true
  naming:
    controller_suffix: Controller
    service_suffix: Service
    repository_suffix: Repository
  logging:
    format: structured_json
    required_fields: [timestamp, level, trace_id, message]

security:
  sql:
    rule: parameterized_only
    no_string_concat: true
  auth:
    rule: require_middleware
    middleware_name: AuthMiddleware
  input_validation:
    rule: validate_all_params
    library: pydantic
  response_filter:
    rule: no_internal_fields
    forbidden_fields: [password_hash, salt, internal_id]

# 需求描述
feature: user_query_api
description: "根据用户 ID 查询用户基本信息，返回姓名、邮箱、角色"
endpoint:
  method: GET
  path: /api/users/{uid}
input:
  uid: string, required, max_length=32
output:
  name: string
  email: string
  role: string

# controller/user_controller.py — 自动生成，符合架构规范
from fastapi import APIRouter, Depends, Request
from dto.user_dto import UserQueryRequest, UserResponse
from service.user_service import UserService
from middleware.auth import AuthMiddleware

router = APIRouter()
router.dependencies.append(Depends(AuthMiddleware))


@router.get("/api/users/{uid}", response_model=UserResponse)
async def get_user(uid: str, request: Request):
    """查询用户基本信息"""
    # 输入校验（security.input_validation 规范要求使用 pydantic）
    validated = UserQueryRequest(uid=uid)

    # 调用 Service 层（architecture 规范：Controller 不直接调 Repository）
    user = await UserService.get_by_id(validated.uid, trace_id=request.state.trace_id)

    if user is None:
        # 编码规范：必须使用自定义 AppError，不允许裸异常
        raise AppError(
            code="USER_NOT_FOUND",
            message=f"User {validated.uid} not found",
            trace_id=request.state.trace_id,
        )

    # 安全规范：响应过滤，不返回内部字段
    return UserResponse(name=user.name, email=user.email, role=user.role)

# service/user_service.py
from repository.user_repository import UserRepository
from dto.user_dto import UserResponse

class UserService:
    @staticmethod
    async def get_by_id(uid: str, trace_id: str) -> UserResponse | None:
        """Service 层：协调 Repository，组装 DTO"""
        model = await UserRepository.find_by_id(uid)
        if model is None:
            return None
        # 日志规范：结构化 JSON，包含必填字段
        logger.info({
            "timestamp": datetime.utcnow().isoformat(),
            "level": "INFO",
            "trace_id": trace_id,
            "message": f"User {uid} queried successfully",
        })
        return UserResponse(name=model.name, email=model.email, role=model.role)

# repository/user_repository.py
from model.user_model import UserModel

class UserRepository:
    @staticmethod
    async def find_by_id(uid: str) -> UserModel | None:
        """Repository 层：安全规范要求参数化 SQL，禁止字符串拼接"""
        # ✅ 参数化查询，符合 security.sql.parameterized_only
        row = await db.execute("SELECT name, email, role FROM users WHERE id = $1", uid)
        if row is None:
            return None
        return UserModel(**row)

✅ architecture: Controller 仅依赖 Service 和 DTO，未直接引用 Repository
✅ security.sql: 所有查询使用参数化方式，未发现字符串拼接
✅ security.auth: 路由已挂载 AuthMiddleware
✅ security.response_filter: 响应 DTO 未包含 forbidden_fields 中的字段
✅ coding.error_handling: 异常均使用 AppError，无裸 raise
⚠️ coding.logging: Service 层日志缺少 level 字段 → 已自动补全