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 可见性。

脚本 scripts

{
  ...
  "scripts": {
    ...
    "build": "rollup -c",
    "base:install": "npm install -D @fastify/cors @fastify/formbody @fastify/multipart commander ejs fastify prettier rimraf",
    "base:reinstall": "rimraf node_modules;npm 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,dict_districts:districts.json[id/name/districts_level_types_id<=6],dict_types:types.json[],dict_types:types1.json[id],dict_types:types2.json[id|key],dict_types:types3.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",
    "layer:zip": "rimraf node_modules;npm install --omit=dev;D:/7-Zip/7z a './node_modules.zip' './node_modules/*';npm run base:reinstall"
    ...
  }
  ...
}

命令 command

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

扩展 extends

插件 plugins

钩子 hooks

beforeQueryOptions