API 设计 / 系统课时

校验输入并隔离注入风险

校验输入并隔离注入风险

GraphQL 能校验字段类型,却不会自动判断字符串是否符合业务规则,也不会替你保证下游 SQL、搜索 DSL 或命令参数安全。本课把边界收紧到 Resolver:先做业务白名单校验,再把数据作为参数绑定,避免把用户输入直接拼进查询文本。

学习目标

  • 区分 GraphQL 类型校验、业务校验与下游参数绑定的职责
  • 为字符串、枚举、排序和分页参数建立明确白名单
  • 用参数化查询阻断 SQL 注入,并识别不能直接绑定的结构性参数

先明确三层安全边界

GraphQL Schema 主要解决“输入长什么样”。例如 limit 是整数、status 是枚举,这能挡住明显的类型错误,但不能判断关键词是否过长、分页是否超限,也不能证明 Resolver 拼接 SQL 时安全。

业务校验解决“这个值是否允许进入业务逻辑”。应在 Resolver 或服务层统一限制长度、字符集、范围和字段组合。下游绑定则解决“数据不能被解释成查询语法”:SQL 使用占位参数,搜索引擎使用结构化 DSL,绝不把原始输入直接插入查询字符串。

用输入类型缩小可表达范围

能用枚举表达的选项不要开放成任意字符串。下面的输入模型把状态、排序方式和分页上限所需的字段提前固定下来,减少 Resolver 需要处理的自由度。

graphql
enum UserStatus {
  ACTIVE
  DISABLED
}

enum UserSort {
  NAME_ASC
  NAME_DESC
}

input SearchUsersInput {
  keyword: String!
  status: UserStatus
  sort: UserSort = NAME_ASC
  limit: Int = 20
}

type User {
  id: ID!
  name: String!
  status: UserStatus!
}

type Query {
  searchUsers(input: SearchUsersInput!): [User!]!
}

这段 Schema 生效后,客户端不能把 status 或 sort 传成任意文本;但 keyword 的长度、字符范围和 limit 的业务上限仍要在服务端校验。

在 Resolver 边界校验并绑定参数

下面用 Python 标准库 sqlite3 模拟 Resolver 收到 GraphQL 参数后的处理。排序字段不能用 ? 绑定,因此必须从固定映射中选择;真正的用户数据都通过占位符传给数据库。

python
import re
import sqlite3

ALLOWED_STATUS = {"ACTIVE", "DISABLED"}
SORT_SQL = {
    "NAME_ASC": "name ASC",
    "NAME_DESC": "name DESC",
}

def escape_like(value: str) -> str:
    # LIKE 中的 % 和 _ 是通配符;如果业务语义是字面匹配,需要额外转义。
    return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")

def validate_input(data: dict) -> tuple[str, str | None, str, int]:
    keyword = str(data.get("keyword", "")).strip()
    status = data.get("status")
    sort = data.get("sort", "NAME_ASC")
    limit = data.get("limit", 20)

    if not 1 <= len(keyword) <= 40:
        raise ValueError("keyword length must be 1..40")
    if not re.fullmatch(r"[\w\s.@+-]+", keyword, flags=re.UNICODE):
        raise ValueError("keyword contains unsupported characters")
    if status is not None and status not in ALLOWED_STATUS:
        raise ValueError("unsupported status")
    if sort not in SORT_SQL:
        raise ValueError("unsupported sort")
    if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 50:
        raise ValueError("limit must be an integer in 1..50")

    return keyword, status, sort, limit

def search_users(conn: sqlite3.Connection, data: dict) -> list[tuple]:
    keyword, status, sort, limit = validate_input(data)

    sql = "SELECT id, name, status FROM users WHERE name LIKE ? ESCAPE '\\'"
    params: list[object] = [f"%{escape_like(keyword)}%"]

    if status is not None:
        sql += " AND status = ?"
        params.append(status)

    # ORDER BY 属于 SQL 结构,只能从服务端白名单映射中选择。
    sql += f" ORDER BY {SORT_SQL[sort]} LIMIT ?"
    params.append(limit)
    return conn.execute(sql, params).fetchall()

def main() -> None:
    conn = sqlite3.connect(":memory:")
    conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, status TEXT)")
    conn.executemany(
        "INSERT INTO users(name, status) VALUES (?, ?)",
        [
            ("alice@example.com", "ACTIVE"),
            ("bob@example.com", "DISABLED"),
        ],
    )

    print(search_users(conn, {
        "keyword": "alice",
        "status": "ACTIVE",
        "sort": "NAME_ASC",
        "limit": 10,
    }))

    try:
        search_users(conn, {"keyword": "alice' OR 1=1 --"})
    except ValueError as exc:
        print(f"rejected: {exc}")

if __name__ == "__main__":
    main()

预期输出

text
[(1, 'alice@example.com', 'ACTIVE')]
rejected: keyword contains unsupported characters

如果数据库驱动、数据内容或排序规则不同,行内容可能不同,但恶意输入应在进入 SQL 前被拒绝。即使去掉字符集限制,? 参数绑定仍会把值当数据处理;业务校验与参数化查询是两层独立防线,不应互相替代。

不要把参数绑定理解成万能转义

参数绑定通常只适用于“值”,不能直接绑定列名、表名、排序方向或运算符。遇到这些结构性参数,应把客户端可选值映射到服务端预定义片段,而不是把用户文本拼接进去。字符白名单应来自业务语义,而不是拿来替代参数绑定;如果合法姓名允许撇号,就应允许该字符并继续依赖参数化查询防注入。

对 Elasticsearch、MongoDB 或内部搜索 DSL 也要遵守同一原则:优先构造结构化对象,只允许白名单字段与操作符,不接受客户端直接提交完整查询表达式。日志中记录拒绝原因和请求标识即可,避免把令牌、密码或完整敏感输入写入日志。

用拒绝路径完成验收

验收时至少覆盖正常值、边界值和恶意值。正常查询应返回预期记录;超长关键词、非法枚举、超限分页应在业务层拒绝;带引号、注释符或查询语法的输入不能改变下游查询结构。只有这三类路径都成立,输入校验与注入隔离才算真正闭环。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

校验输入并隔离注入风险

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通