API 设计 / 系统课时
校验输入并隔离注入风险
校验输入并隔离注入风险
GraphQL 能校验字段类型,却不会自动判断字符串是否符合业务规则,也不会替你保证下游 SQL、搜索 DSL 或命令参数安全。本课把边界收紧到 Resolver:先做业务白名单校验,再把数据作为参数绑定,避免把用户输入直接拼进查询文本。
学习目标
- 区分 GraphQL 类型校验、业务校验与下游参数绑定的职责
- 为字符串、枚举、排序和分页参数建立明确白名单
- 用参数化查询阻断 SQL 注入,并识别不能直接绑定的结构性参数
先明确三层安全边界
GraphQL Schema 主要解决“输入长什么样”。例如 limit 是整数、status 是枚举,这能挡住明显的类型错误,但不能判断关键词是否过长、分页是否超限,也不能证明 Resolver 拼接 SQL 时安全。
业务校验解决“这个值是否允许进入业务逻辑”。应在 Resolver 或服务层统一限制长度、字符集、范围和字段组合。下游绑定则解决“数据不能被解释成查询语法”:SQL 使用占位参数,搜索引擎使用结构化 DSL,绝不把原始输入直接插入查询字符串。
用输入类型缩小可表达范围
能用枚举表达的选项不要开放成任意字符串。下面的输入模型把状态、排序方式和分页上限所需的字段提前固定下来,减少 Resolver 需要处理的自由度。
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 参数后的处理。排序字段不能用 ? 绑定,因此必须从固定映射中选择;真正的用户数据都通过占位符传给数据库。
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()预期输出
[(1, 'alice@example.com', 'ACTIVE')]
rejected: keyword contains unsupported characters如果数据库驱动、数据内容或排序规则不同,行内容可能不同,但恶意输入应在进入 SQL 前被拒绝。即使去掉字符集限制,? 参数绑定仍会把值当数据处理;业务校验与参数化查询是两层独立防线,不应互相替代。
不要把参数绑定理解成万能转义
参数绑定通常只适用于“值”,不能直接绑定列名、表名、排序方向或运算符。遇到这些结构性参数,应把客户端可选值映射到服务端预定义片段,而不是把用户文本拼接进去。字符白名单应来自业务语义,而不是拿来替代参数绑定;如果合法姓名允许撇号,就应允许该字符并继续依赖参数化查询防注入。
对 Elasticsearch、MongoDB 或内部搜索 DSL 也要遵守同一原则:优先构造结构化对象,只允许白名单字段与操作符,不接受客户端直接提交完整查询表达式。日志中记录拒绝原因和请求标识即可,避免把令牌、密码或完整敏感输入写入日志。
用拒绝路径完成验收
验收时至少覆盖正常值、边界值和恶意值。正常查询应返回预期记录;超长关键词、非法枚举、超限分页应在业务层拒绝;带引号、注释符或查询语法的输入不能改变下游查询结构。只有这三类路径都成立,输入校验与注入隔离才算真正闭环。