input-validation

输入校验

何时用

• 编写 API 接口、表单处理、文件上传等接收外部数据的代码时。
• 处理来自消息队列、第三方 Webhook、数据库读回等任何外部数据源时。
• 发现生产环境出现类型错误、字段缺失崩溃、注入攻击等问题时。
• 做安全审查时检查系统边界的防御是否完整。

核心规则

1. 在系统边界集中校验：类型、范围、格式、必填

规则： 在 API 入口（controller/route handler）对所有外部输入做统一校验，覆盖类型是否正确、数值是否在合法范围内、字符串格式是否符合预期、必填字段是否存在；校验通过后的数据才传入业务逻辑层。

为什么： AI 生成 API 接口时最常见的模式是直接把 request.json 传进业务函数，让业务函数自己处理字段缺失或类型错误。这导致两个问题：一是 AttributeError/KeyError 在内层崩溃，堆栈信息可能暴露内部结构；二是相同的校验逻辑散落在各处，维护困难，容易漏掉。AI 还经常只校验"快乐路径"，完全忽略 age=-1、quantity=99999999、email=""等边界值。

怎么做：

from pydantic import BaseModel, Field, field_validator
from typing import Literal

class CreateOrderRequest(BaseModel):
    product_id: int = Field(gt=0)                    # ✅ 类型 + 范围
    quantity: int = Field(ge=1, le=100)              # ✅ 1~100 之间
    email: str = Field(pattern=r'^[\w.+-]+@[\w-]+\.[a-z]{2,}$')  # ✅ 格式
    channel: Literal["web", "app", "api"]            # ✅ 枚举白名单

@app.post("/orders")
def create_order(body: CreateOrderRequest):          # ✅ 入口即校验
    return order_service.create(body)                # 业务层拿到的已是合法数据

• 使用 Pydantic（Python）、Zod（TypeScript）、Joi（Node.js）等成熟校验库，不手写正则堆砌。

---

2. 白名单优先于黑名单；枚举/路径/文件名严格限定

规则： 对枚举值用白名单（只接受已知合法值），不用黑名单（拒绝已知危险值）；文件名和路径做规范化后校验，防止路径穿越（../../../etc/passwd）；用户可控的文件名只允许 [a-zA-Z0-9._-]。

为什么： AI 实现文件操作时惯用黑名单：if ".." in filename: reject。这类黑名单极容易被绕过——URL 编码 %2e%2e、双重编码 %252e%252e、Unicode 等价字符都能轻易规避。路径穿越漏洞至今仍是 OWASP Top 10 常见漏洞之一，很大程度上因为开发者（包括 AI）低估了绕过黑名单的攻击面。

怎么做：

import os
import re

ALLOWED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".pdf"}
UPLOAD_BASE = "/var/uploads"

def safe_filename(user_filename: str) -> str:
    # ✅ 白名单字符集：只保留安全字符
    name = re.sub(r'[^a-zA-Z0-9._-]', '_', os.path.basename(user_filename))
    ext = os.path.splitext(name)[1].lower()

    # ✅ 扩展名白名单
    if ext not in ALLOWED_EXTENSIONS:
        raise ValueError(f"不支持的文件类型: {ext}")
    return name

def safe_path(base_dir: str, user_path: str) -> str:
    # ✅ 规范化后确认仍在 base_dir 内，防路径穿越
    full = os.path.realpath(os.path.join(base_dir, user_path))
    if not full.startswith(os.path.realpath(base_dir) + os.sep):
        raise ValueError("路径穿越攻击")
    return full