Serverless GraphQL API 模板（简介与设计说明）

项目说明

本仓库为可复用的 Serverless GraphQL API 模板与命令行工具（sga），目标是将常见的 GraphQL 服务架构、生成器、运行时上下文和部署打包流程抽象出来，方便快速启动、验证与可扩展化开发。此 README 侧重于项目结构、设计理念、功能边界及扩展点，而非具体示例调用。

---

设计目标（为什么存在）

- 统一：提供一套约定优于配置的项目结构，减少每次新建 GraphQL 服务的重复工作。
- 可扩展：通过模板、hooks 与命令扩展点，支持自定义模型、解析器与运行时行为。
- Serverless 优化：支持将业务打包为适配 Lambda/云函数的产物（包括 layer 打包流程）。
- 开发效率：生成器 + nodemon 热重载可快速从模型/模板到可运行服务的闭环。
- 可测试：提供快速验证脚本与构建后测试入口，便于 CI 集成。

---

主要功能（概览）

- 项目初始化（init）
- 生成约定的目录结构、模板文件与基础配置（env、rollup、nodemon 等）。
- 模板生成（generate-files / generate-clear）
- 基于 EJS 模板生成 Model、Resolver、Schema、Type 等源文件，支持清理已生成文件。
- 依赖管理与打包（install / layer:zip / build）
- 提供脚本帮助生成可用于 Serverless 的 node_modules 压缩包（Lambda layer）及 rollup 打包产物。
- 本地开发支持（serviceStart / nodemon）
- 支持热重载与自动生成，减少开发—验证循环时间。
- Schema 导出（introspection）
- 从运行服务导出 introspection 数据或 SDL，用于前端 codegen、文档或审计。
- 通用运行时工具
- JWT 签发/校验、基于角色的 permissionFilter、DataLoader 模式以减少 N+1 查询。

---

核心约定与工作流

- Model 定义驱动：模型（简化的 schema/字段定义）作为生成器输入，解析器与 GraphQL 类型通过模板自动生成骨架。
- Context 注入：运行时通过 context 注入 models、dataLoaders、user 与权限检查函数，解析器只关注业务逻辑。
- Hook 机制：模板中预留 hooks（例如 src.options.hooks.js.template）供项目在查询前、查询后、错误处理等阶段挂载自定义逻辑。
- 最小侵入：生成的代码为可编辑的模板输出，项目生成后可按需替换模板实现，生成器只负责初始骨架与重复性代码。

---

安全与生产建议

- 秘钥管理：模板提供示例 key，生产环境需从安全存储服务读取，避免直接在代码中暴露密钥。
- 权限与审计：借助 permissionFilter + hooks 实现统一权限判断与请求链路审计（支持扩展到 ABAC、策略引擎）。
- 性能优化：默认提供 DataLoader 模板，可避免 N+1 查询；可在 hooks 中统一处理缓存、熔断与限流。
- 可测试性与监控：context 中统一注入 logger/metrics 接口可方便扩展，结合 introspection 保持 schema 可见性。

$3

``json
{
...
"scripts": {
...
"build": "rollup -c",
"base:install-dev": "npm install -D @fastify/cors @fastify/formbody @fastify/multipart commander ejs fastify prettier rimraf",
"base:install-prod": "npm install dotenv sequelize mysql2 jsonwebtoken nodejs-jsencrypt crypto-js dataloader",
"base:reinstall": "rimraf node_modules;npm run base:install",
"sga:init": "sga init",
"sga:install": "sga install",
"sga:latest": "npm install @uni2c/serverless-graphql-api@latest",
"sga:generate:files": "sga generate-files",
"sga:generate:dict": "sga generate-dict --dict_tables \"dict_districts:districts.json[id/parent_id|districts_level_types_id|citycode|adcode|name|short_name|longitude|latitude|comment|sort_order/districts_level_types_id<=6],dict_types:types.json[id|key/key|name|setting]\"",
"sga:generate:clear": "sga generate-clear",
"sga:generate:extends": "sga generate-extends",
"sga:generate:start": "nodemon",
"sga:introspection": "sga introspection http://localhost:8000/v3?momoca=123456",
"test:src": "node ./test.js ./src/index.js",
"test:build": "node ./test.js ./index.js",
"publish:serverless-build-http": "npm run build && publish_tools serverless-build-file ./http_file.json --functionname v3 --namespace default",
"layer:zip": "rimraf node_modulesn node_modules.zip --no-glob;node -e \"console.log('clear done,wite 10s');setTimeout(() => {}, 10000)\";npm install --omit=dev;D:/7-Zip/7z a ./node_modules.zip ./node_modules/*;npm run base:reinstall",
"base:install": "npm install"
...
}
...
}
`

$3

npm install -D @fastify/cors @fastify/formbody @fastify/multipart commander ejs fastify prettier rimraf`

$3

$3

$3

#### beforeQueryOptions