API 设计 / 系统课时
实施字段级授权
实施字段级授权
本课把授权从“根 Resolver 里判断一次角色”细化到对象、字段和业务动作三个层次。你将实现可运行的 Apollo Server 示例:对象不可见时隐藏资源,敏感字段单独拒绝,修改动作再按所有权或管理员身份检查。
学习目标
- 区分对象级、字段级与业务动作级授权各自保护的边界。
- 在具体字段 Resolver 中执行最小权限检查,避免根节点授权被子字段绕过。
- 设计拒绝策略,使不存在、不可见和无权修改等场景不会意外泄漏敏感信息。
为什么根 Resolver 检查不够
GraphQL 客户端可以自由选择字段。即使 Query.project 已确认用户能看到某个项目,也不代表该用户可以读取项目上的 secretNotes;同样,能读取对象也不代表能执行 renameProject。

授权规则最好围绕资源和动作表达,例如“用户是否能查看这个项目”“用户是否能读取这个敏感字段”“用户是否能重命名这个项目”。这样规则可以复用,也更容易测试,而不是把大量 if (role === ...) 散在业务代码里。
实现三层授权
示例使用 Node.js 20+、Apollo Server 5 与 GraphQL.js 16.11+。为聚焦授权逻辑,x-demo-user 只用于模拟“认证层已经得到可信用户”;生产环境绝不能信任客户端直接声明用户名或角色。
npm install @apollo/server@^5 graphql@^16.11预期结果:
安装完成,npm 进程退出码为 0;added/audited 数量会随锁文件变化。保存为 server.mjs:
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { GraphQLError } from 'graphql';
const users = new Map([
['alice', { id: 'u1', role: 'MEMBER' }],
['bob', { id: 'u2', role: 'MEMBER' }],
['admin', { id: 'u3', role: 'ADMIN' }],
]);
const projects = new Map([
['p1', {
id: 'p1',
name: 'Roadmap',
ownerId: 'u1',
memberIds: ['u1', 'u2'],
secretNotes: 'Budget freeze',
}],
]);
const typeDefs = `#graphql
type Project {
id: ID!
name: String!
ownerId: ID!
secretNotes: String
}
type Query {
project(id: ID!): Project
}
type Mutation {
renameProject(id: ID!, name: String!): Project!
}
`;
function requireUser(contextValue) {
if (contextValue.user) return contextValue.user;
throw new GraphQLError('需要有效身份', {
extensions: { code: 'UNAUTHENTICATED' },
});
}
function canSeeProject(user, project) {
return user.role === 'ADMIN' || project.memberIds.includes(user.id);
}
function canRenameProject(user, project) {
return user.role === 'ADMIN' || project.ownerId === user.id;
}
const resolvers = {
Query: {
project: (_, { id }, contextValue) => {
const user = requireUser(contextValue);
const project = projects.get(id);
// 对象不可见时返回 null,避免向无权用户确认资源是否存在。
if (!project || !canSeeProject(user, project)) return null;
return project;
},
},
Project: {
secretNotes: (project, _, contextValue) => {
const user = requireUser(contextValue);
// 即使父对象可见,敏感字段仍要独立授权。
if (user.role !== 'ADMIN') {
throw new GraphQLError('无权读取 secretNotes', {
extensions: { code: 'FORBIDDEN' },
});
}
return project.secretNotes;
},
},
Mutation: {
renameProject: (_, { id, name }, contextValue) => {
const user = requireUser(contextValue);
const project = projects.get(id);
if (!project || !canSeeProject(user, project)) {
throw new GraphQLError('项目不存在', {
extensions: { code: 'NOT_FOUND' },
});
}
if (!canRenameProject(user, project)) {
throw new GraphQLError('无权重命名项目', {
extensions: { code: 'FORBIDDEN' },
});
}
project.name = name;
return project;
},
},
};
const server = new ApolloServer({
typeDefs,
resolvers,
includeStacktraceInErrorResponses: false,
});
const { url } = await startStandaloneServer(server, {
listen: { port: 4000 },
context: async ({ req }) => {
const demoName = req.headers['x-demo-user'];
const user = typeof demoName === 'string'
? users.get(demoName) ?? null
: null;
return { user };
},
});
console.log(`Server ready at ${url}`);启动服务:
node server.mjs预期输出:
Server ready at http://localhost:4000/验证字段和动作授权
先让项目所有者 Alice 查询普通字段与敏感字段,再让 Bob 尝试重命名同一项目:
curl -s http://localhost:4000/ -H 'content-type: application/json' -H 'x-demo-user: alice' --data '{"query":"query { project(id: \"p1\") { id name secretNotes } }"}'
curl -s http://localhost:4000/ -H 'content-type: application/json' -H 'x-demo-user: bob' --data '{"query":"mutation { renameProject(id: \"p1\", name: \"New Name\") { id name } }"}'预期结果:
第一条请求:project.id 与 project.name 正常返回;secretNotes 为 null,并在 errors 中出现 extensions.code=FORBIDDEN。
第二条请求:renameProject 被拒绝,errors 中出现 extensions.code=FORBIDDEN,项目名称保持 Roadmap。字段级拒绝发生在一个可空字段上,因此 GraphQL 可以把 secretNotes 置为 null,同时保留同一对象中已经成功解析的其他字段。如果敏感字段被声明为非空,错误可能触发 GraphQL 的 null bubbling,让更上层对象也变成 null,Schema 设计时要把这一行为纳入考虑。
让授权规则跟着数据边界走
对象级授权适合决定某条资源能否进入 GraphQL 结果,字段级授权适合保护同一对象中权限不同的属性,业务动作授权则保护“修改、发布、退款、审批”这类有副作用的能力。三者可以共享策略函数,但不应互相替代。
高敏感系统还应在服务层或数据层保留第二道授权边界,避免 GraphQL 之外的调用路径绕过检查。Resolver 负责把 GraphQL 字段和业务权限连接起来,但真正的安全边界不应只依赖“某个根 Resolver 已经检查过一次”。