API 设计 / 系统课时
收紧生产端点暴露面
收紧生产端点暴露面
生产 GraphQL 端点不应把开发便利直接带到公网。本课用 Apollo Server 5 与 Express 5 把 Introspection、CORS、CSRF 和错误响应分别收紧,并通过真实请求验证每一道边界是否按预期工作。
学习目标
- 根据环境显式控制 Introspection 与 Schema 细节暴露。
- 为浏览器来源配置最小 CORS 白名单,并保持 CSRF 防护开启。
- 对内部异常做错误脱敏,并用请求验证生产配置。
把暴露面拆成四层
这四项保护解决的问题不同。Introspection 控制客户端能否直接枚举 Schema;CORS 约束浏览器脚本能否读取跨源响应;CSRF 防护阻止“简单请求”绕过预检去触发 GraphQL 操作;错误脱敏则避免把堆栈、数据库信息或内部服务细节返回给客户端。

使用显式生产配置
下面示例要求 Node.js 20+,并使用 @apollo/server 5、graphql 16.11+、Express 5、@as-integrations/express5 与 cors。生产行为由代码显式决定,而不是依赖某个部署平台恰好设置了正确的环境默认值。
import http from 'node:http';
import express from 'express';
import cors from 'cors';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@as-integrations/express5';
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
import { ApolloServerPluginLandingPageDisabled } from '@apollo/server/plugin/disabled';
const isProduction = process.env.NODE_ENV === 'production';
const allowedOrigin =
process.env.ALLOWED_ORIGIN ?? 'https://app.example.com';
const typeDefs = `#graphql
type Query {
ping: String!
secretError: String
}
`;
const resolvers = {
Query: {
ping: () => 'pong',
secretError: () => {
throw new Error('db password=do-not-expose');
},
},
};
const app = express();
app.disable('x-powered-by');
const httpServer = http.createServer(app);
const server = new ApolloServer({
typeDefs,
resolvers,
introspection: !isProduction,
hideSchemaDetailsFromClientErrors: isProduction,
csrfPrevention: true,
includeStacktraceInErrorResponses: !isProduction,
formatError(formattedError) {
if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
return {
message: 'Internal server error',
extensions: { code: 'INTERNAL_SERVER_ERROR' },
};
}
return formattedError;
},
plugins: [
ApolloServerPluginLandingPageDisabled(),
ApolloServerPluginDrainHttpServer({ httpServer }),
],
});
await server.start();
app.use(
'/graphql',
cors({ origin: [allowedOrigin], credentials: true }),
express.json({ limit: '100kb' }),
expressMiddleware(server),
);
await new Promise((resolve) => httpServer.listen({ port: 4000 }, resolve));
console.log('GraphQL ready at http://localhost:4000/graphql');预期结果:保存为 server.mjs 后可以直接启动;生产模式下 Introspection 与字段名建议被收紧,Apollo 落地页关闭,内部错误会经过统一脱敏。
NODE_ENV=production ALLOWED_ORIGIN=https://app.example.com node server.mjs预期输出
GraphQL ready at http://localhost:4000/graphql验证每一道边界
先验证允许来源和正常查询。响应应包含允许的跨域来源,并返回 pong。
curl -si -X POST http://localhost:4000/graphql \
-H 'Origin: https://app.example.com' \
-H 'Content-Type: application/json' \
--data '{"query":"{ ping }"}'预期输出
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
<VALUE>
{"data":{"ping":"pong"}}<VALUE> 代表日期、连接策略等与运行环境有关的响应头,实际值可能不同。再检查未授权来源是否拿不到 CORS 许可头,以及内部异常是否只暴露稳定错误信息。
curl -si -X POST http://localhost:4000/graphql \
-H 'Origin: https://evil.example' \
-H 'Content-Type: application/json' \
--data '{"query":"{ ping }"}' \
| grep -i '^Access-Control-Allow-Origin:' || echo 'no ACAO header'
curl -s -X POST http://localhost:4000/graphql \
-H 'Content-Type: application/json' \
--data '{"query":"{ secretError }"}'预期输出
no ACAO header
{"errors":[{"message":"Internal server error","extensions":{"code":"INTERNAL_SERVER_ERROR"}}],"data":{"secretError":null}}最后用一个没有预检触发头的 GET 请求验证 CSRF 防护。此请求不应执行 GraphQL 查询。
curl -si 'http://localhost:4000/graphql?query=%7Bping%7D'预期输出
HTTP/1.1 400 Bad Request
<VALUE>响应正文会说明请求未满足 CSRF 防护要求,具体错误文本可能随补丁版本变化。若业务确实允许 GET 查询,应让受信客户端发送能触发预检的非空请求头,而不是关闭 csrfPrevention。客户端错误脱敏后,原始异常仍应写入受控的服务端日志或 Trace,不能为了“安全”把排障证据一起丢掉。
生产策略不要只看一个开关
关闭 Introspection 只能降低 Schema 的直接可发现性,不能代替授权;CORS 只影响浏览器;错误脱敏也不能阻止高成本查询。真正的生产收口应把这些设置与身份认证、字段级授权、查询深度或成本限制、速率限制以及网关访问策略组合起来。