# 掌握 Hasura GraphQL 引擎使用 Hasura 构建生产就绪的 GraphQL API 的综合技能。掌握现代应用程序的即时 API 生成、精细权限、身份验证集成、事件驱动架构、自定义业务逻辑和远程模式拼接。 ## 何时使用此技能在以下情况下使用 Hasura GraphQL Engine： * 无需编写后端代码即可快速构建 GraphQL API * 需要现有 PostgreSQL 数据库的即时 CRUD API * 实施细粒度的行级和列级安全性 * 使用 GraphQL 订阅构建实时应用程序 * 集成多个数据源（数据库、REST API、GraphQL 服务） * 使用数据库触发器创建事件驱动架构 * 通过 Actions 使用自定义业务逻辑扩展 GraphQL * 在API层实现认证和授权 * 快速构建管理面板、仪表板或内部工具 * 从 REST 迁移到 GraphQL，无需重写后端 * 需要生产就绪的功能（缓存、速率限制、监控） * 构建具有基于角色的访问的多租户 SaaS 应用程序 ## 核心概念 ### 即时 GraphQL API 生成 Hasura 的主要价值主张是从数据库模式自动生成 GraphQL API： * **表跟踪** ：将 Hasura 指向 PostgreSQL 表以立即获取查询、突变和订阅 * **关系检测** ：自动将外键关系推断为 GraphQL 连接 * **类型安全**：数据库模式直接转换为 GraphQL 类型 * **零代码** ：无需编写解析器，无需 ORM 配置，无需样板 * **默认实时** ：每个查询自动有一个订阅对应项 **它是如何工作的：** 1. 将 Hasura 连接到 PostgreSQL 数据库 2. Hasura 控制台中的跟踪表 3. GraphQL API 可立即使用： * `query` \- 通过过滤、排序、分页获取数据 * `mutation` \- 插入、更新、删除操作 * `subscription` \- 通过 WebSockets 实时更新数据 ### 元数据驱动架构 Hasura 是 **元数据驱动** ，而不是代码驱动： * **元数据** ：定义 API 的 JSON/YAML 配置 * **声明式** ：定义你想要什么，而不是如何实现它 * **版本控制** : 元数据文件可以提交到 Git * **CLI 迁移** ：Hasura CLI 管理元数据和迁移 * **程序控制**：用于自动化的元数据 API **关键元数据组件：** * 表跟踪和关系 * 权限规则 * 远程模式 * 行动 * 事件触发器 * 自定义功能 ### 权限系统 Hasura 的 **权限系统** 是其最强大的功能，可实现细粒度的访问控制： * **基于角色** ：定义每个角色的每个 GraphQL 操作的权限 * **行级安全性** ：控制用户可以访问哪些行 * **列级安全性**：隐藏特定角色的敏感列 * **会话变量** ：基于 JWT 声明或 webhook 数据的动态权限 * **检查约束**：确定访问的布尔表达式 **权限类型：** * `select` \- 读取权限 * `insert` \- 创建权限 * `update` \- 修改权限 * `delete` \- 删除权限 ### 身份验证集成 Hasura **将身份验证委托给您的身份验证服务，但 **处理授权** ： * **JWT 模式** ：验证包含用户声明的 JWT 令牌 * **Webhook模式** : 调用webhook获取会话变量 * **会话变量**：`x-hasura-role`、`x-hasura-user-id`、自定义声明 * **多提供商** ：支持 Auth0、Firebase、Cognito、自定义身份验证 **授权流程：** 1. 用户使用您的身份验证服务进行身份验证（Auth0、Firebase、自定义） 2. Auth 服务使用 Hasura 声明发出 JWT 3.客户端在Authorization header中发送JWT 4. Hasura验证JWT并提取会话变量 5. 使用会话变量评估权限 6. 使用适当的访问控制执行 GraphQL 查询 ### 事件触发器 **事件触发器** 通过在数据库更改时调用 Webhook 来启用事件驱动的架构： * **数据库事件**：INSERT、UPDATE、DELETE 触发器 * **可靠交付**：至少一次交付并重试 * **Payload** ：JSON 中的旧行和新行数据 * **异步处理**：长时间运行的任务，外部集成 * **用例**：发送电子邮件、同步到 Elasticsearch、更新缓存、触发工作流程 ### 行动 **Actions** 使用自定义业务逻辑扩展 Hasura： * **自定义突变** ：定义由您的代码处理的 GraphQL 突变 * **自定义查询** ：添加数据库访问之外的自定义查询逻辑 * **REST 集成** ：从 GraphQL 调用 REST API * **类型安全**：在 GraphQL SDL 中定义输入/输出类型 * **Handler** ：您的 HTTP 端点接收 GraphQL 变量 **常见用例：** * 付款处理 * 复杂的验证 * 第三方API调用 * 自定义算法 * 文件上传 * 邮件发送 ### 远程模式 **远程模式**通过合并外部 GraphQL API 来启用模式拼接： * **Schema Stitching** ：统一多个 GraphQL 服务 * **类型扩展** ：使用远程模式中的字段扩展类型 * **权限** ：将基于角色的权限应用于远程模式 * **命名空间** ：隔离远程模式以避免冲突 * **用例**：微服务、旧版 GraphQL API、第三方服务 ### 实时订阅 Hasura 提供**原生 GraphQL 订阅**： * **实时查询** ：数据变化时自动推送更新 * **WebSocket 协议** ：高效的双向通信 * **多路复用**：优化许多并发客户端的订阅 * **过滤** ：订阅特定的数据子集 * **轮询回退**：针对受限网络的基于 HTTP 的流式传输 ## 权限系统深入探讨 ### 行级安全性行级安全性使用**布尔检查表达式**来过滤可访问的行： **示例：用户只能看到自己的数据** { “检查”：{ “用户 ID”：{ "_eq": "X-Hasura-用户 ID" } } } **示例：多租户数据隔离** { “检查”：{ “租户id”：{ "_eq": "X-Hasura-租户-Id" } } } **示例：复杂的访问规则** { “检查”：{ “_或”：[ { “用户 ID”：{ "_eq": "X-Hasura-用户 ID" } }, { “是公共”：{ “_eq”：正确 } } ] } } ### 列级安全性控制每个角色哪些列可见： **示例：隐藏敏感用户字段** 选择：列： - 身份证号 - 用户名 - 电子邮件 # 密码哈希被隐藏 #created_at 被隐藏 **示例：不同角色的不同视图** # 管理员角色可以查看所有列选择：列：“*” # 用户角色只能看到有限的列选择：列： - 身份证号 - 用户名 - 个人资料图片 ### 插入权限控制可以插入哪些数据： **示例：从会话中设置 user_id** { “检查”：{ “用户 ID”：{ "_eq": "X-Hasura-用户 ID" } }, “设置”：{ "user_id": "X-Hasura-用户 ID" } } **示例：插入前验证所有权** { “检查”：{ “项目”：{ “所有者 ID”：{ "_eq": "X-Hasura-用户 ID" } } } } ### 更新权限控制可以更新哪些行以及可以设置哪些值： **示例：仅更新自己的数据** { “过滤器”：{ “用户 ID”：{ "_eq": "X-Hasura-用户 ID" } }, “检查”：{ “用户 ID”：{ "_eq": "X-Hasura-用户 ID" } }, “设置”：{ “updated_at”：“现在（）” } } **filter** ：可以选择哪些行进行更新 **check** ：更新完成后验证 **set** ：自动设置列值 ### 删除权限控制可以删除哪些行： **示例：仅删除自己的数据** { “过滤器”：{ “用户 ID”：{ "_eq": "X-Hasura-用户 ID" } } } ## 身份验证集成 ### JWT 模式配置配置 Hasura 以验证 JWT 令牌： **环境变量：** HASURA_GRAPHQL_JWT_SECRET='{ “类型”：“RS256”， "key": "-----开始公钥-----\n...\n-----结束公钥-----" }' **智威汤逊索赔结构：** { “子”：“用户123”， “iat”：1633024800， “经验”：1633111200， “https://hasura.io/jwt/claims”：{ "x-hasura-default-role": "用户", "x-hasura-allowed-roles": ["用户", "管理员"], "x-hasura-user-id": "user123", “x-hasura-org-id”：“org456” } } **所需索赔：** * `x-hasura-default-role`: 如果请求中未指定则默认角色 * `x-hasura-allowed-roles`：用户可以承担的角色数组 * 自定义声明，例如用于权限检查的“x-hasura-user-id” ### Auth0 集成 **Auth0 规则添加 Hasura 声明：** 函数（用户、上下文、回调）{ const 命名空间 = "https://hasura.io/jwt/claims"; context.idToken[命名空间] = { 'x-hasura-default-role': '用户', 'x-hasura-allowed-roles': ['用户'], 'x-hasura-user-id': user.user_id }; 回调（空，用户，上下文）； } **客户端使用情况：** const token = 等待 auth0Client.getTokenSilently(); const 响应 = 等待 fetch('https://my-hasura.app/v1/graphql', { 方法：'POST'，标题：{ '授权': `不记名${token}`, '内容类型'：'应用程序/json' }, 正文： JSON.stringify({ 查询，变量 }) }); ### Firebase 集成 **Firebase 自定义声明：** // 管理SDK const admin = require('firebase-admin'); 异步函数 setCustomClaims(uid) { 等待 admin.auth().setCustomUserClaims(uid, { 'https://hasura.io/jwt/claims': { 'x-hasura-default-role': '用户', 'x-hasura-allowed-roles': ['用户'], 'x-hasura-用户-id'：uid } }); } ### Webhook 模式 JWT 的替代方案 - Hasura 为每个请求调用您的 webhook： **Webhook 端点：** app.post('/auth-webhook', async (req, res) => { const authHeader = req.headers['授权']; // 验证令牌（你的逻辑） const 用户 = 等待 validateToken(authHeader); 如果（！用户）{ return res.status(401).json({ message: '未经授权' }); } // 返回会话变量 res.json({ 'X-Hasura-User-Id': user.id, 'X-Hasura-Role': user.role, 'X-Hasura-Org-Id': user.orgId }); }); **哈苏拉配置：** HASURA_GRAPHQL_AUTH_HOOK=https://myapp.com/auth-webhook HASURA_GRAPHQL_AUTH_HOOK_MODE=POST ## 事件触发器 ### 创建事件触发器事件触发器在数据库更改时调用 Webhook： **通过控制台：** 1. 导航至“事件”选项卡 2. 创建触发器 3.选择表和操作（INSERT、UPDATE、DELETE） 4. 提供 webhook URL 5.配置重试和超时设置 **通过元数据 API：** POST /v1/元数据 HTTP/1.1 内容类型：application/json X-Hasura-角色：admin { “类型”：“创建事件触发”， “参数”：{ “名称”：“用户创建”， “表”：{ “名称”：“用户”， “模式”：“公共” }, "webhook": "https://myapp.com/webhooks/user-created", “插入”：{ “列”：“*” }, “重试配置”：{ “重试次数”：3， “间隔秒”：10， “超时秒”：60 } } } ### 事件有效负载结构 Webhook 接收结构化 JSON 负载： { “事件”：{ “会话变量”：{ "x-hasura-role": "用户", “x-hasura-用户-id”：“123” }, “操作”：“插入”， “数据”：{ “旧”：空， “新”：{ "id": "uuid-这里", “电子邮件”：“user@example.com”， “创建时间”：“2025-01-15T10:30:00Z” } } }, “创建时间”：“2025-01-15T10：30：00.123456Z”， "id": "事件 ID", “触发”：{ “名称”：“用户创建” }, “表”：{ “模式”：“公共”， “名称”：“用户” } } ### 事件触发器用例 **发送欢迎电子邮件：** // Webhook 处理程序 app.post('/webhooks/user-created', async (req, res) => { const { 事件 } = req.body; const 用户 = event.data.new; 等待发送电子邮件({ 至：用户.电子邮件，主题：“欢迎！”，模板：'欢迎'，数据：{ 名称：用户名 } }); res.json({ 成功: true }); }); **同步到Elasticsearch：** app.post('/webhooks/product-updated', async (req, res) => { const { 事件 } = req.body; const 产品 = event.data.new; 等待 esClient.index({ 索引：'产品'， id: 产品.id, 主体：产品 }); res.json({ 成功: true }); }); **触发工作流程：** app.post('/webhooks/order-placed', async (req, res) => { const { 事件 } = req.body; const order = event.data.new; // 触发支付处理等待 processPayment(order.id); // 通知库存系统等待 updateInventory(order.items); // 发送确认邮件等待发送订单确认（订单）； res.json({ 成功: true }); }); ## 操作（自定义业务逻辑） ### 定义操作操作通过自定义突变和查询扩展 GraphQL： **GraphQL SDL 定义：** 类型突变 { 登录（用户名：字符串！，密码：字符串！）：LoginResponse } 类型登录响应{ 访问令牌：字符串！刷新令牌：字符串！用户：用户！ } **动作配置：** - 名称：登录定义：种类: 同步处理程序：https://myapp.com/actions/login forward_client_headers：true 标题： - 名称：X-API-密钥值：秘密密钥权限： - 角色：匿名 ### 操作处理程序实现 **Express.js 处理程序：** app.post('/actions/login', async (req, res) => { const { 输入，session_variables } = req.body; const { 用户名，密码 } = 输入； // 验证凭证 const user = wait validateCredentials(用户名, 密码); 如果（！用户）{ 返回 res.status(401).json({ 消息：“凭据无效” }); } // 生成令牌 const accessToken =generateJWT(用户); const refreshToken =generateRefreshToken(用户); // 返回动作响应 res.json({ 访问令牌，刷新令牌，用户：{ id: 用户.id, 用户名：用户.用户名，电子邮件：用户.电子邮件 } }); }); ### 操作权限控制哪些角色可以执行操作： **通过元数据 API：** POST /v1/元数据 HTTP/1.1 内容类型：application/json X-Hasura-角色：admin { “类型”：“创建操作权限”， “参数”：{ "action": "插入作者", “角色”：“用户” } } **多重角色：** 权限： - 角色：用户 - 角色：管理员 - 角色：匿名 ### 动作类型 **同步动作：** * 客户端等待响应 * 用于：登录、付款、验证 * 超时：可配置（默认30秒） **异步操作：** * 立即返回动作ID * 用于：长时间运行的任务、批处理 * 轮询完成或使用 webhook ### 高级动作模式 **付款处理：** 类型突变 { 流程付款( 订单ID：ID！金额：浮动！货币：字符串！付款方式：字符串！ ): 付款响应 } 类型付款响应{ 成功：布尔值！交易ID：字符串错误：字符串 } **文件上传：** 类型突变 { 上传文件( 文件：字符串！ # Base64编码文件名：字符串！ mime类型：字符串！ ): 文件上传响应 } 类型文件上传响应{ 网址：字符串！文件ID：ID！ } **复杂验证：** 类型突变 { 创建项目（名称：字符串！描述：字符串！团队成员：[ID！]！ ): 创建项目响应 } 类型 CreateProjectResponse { 项目：项目错误：[验证错误！] } 类型验证错误{ 字段：字符串！消息：字符串！ } ## 远程模式 ### 添加远程模式集成外部 GraphQL API： **通过元数据 API：** POST /v1/元数据 HTTP/1.1 内容类型：application/json X-Hasura-角色：admin { “类型”：“add_remote_schema”， “参数”：{ “名称”：“auth0_api”， “定义”：{ “url”：“https://myapp.auth0.com/graphql”， “标题”：[ { "name": "授权", "value": "持有者 ${AUTH0_TOKEN}" } ], “forward_client_headers”：假， “超时秒数”：60 } } } ### 远程模式定制自定义类型和字段名称以避免冲突： { “类型”：“add_remote_schema”， “参数”：{ “名称”：“国家”， “定义”：{ “url”：“https://countries.trevorblades.com/graphql”， “定制”：{ "root_fields_namespace": "countries_api", “类型名称”：{ “前缀”：“国家_”， “后缀”：“_类型” }, “字段名称”：[ { "parent_type": "国家", “前缀”：“国家_” } ] } } } } ### 远程架构权限将基于角色的权限应用于远程模式： **原始远程架构：** 类型用户{ 身份证：身份证！名字：字符串！姓氏：字符串！电话：字符串！电子邮件：字符串！ } 类型查询{ user(id: ID!): 用户 get_users_by_name（名字：字符串！，姓氏：字符串）：[用户] } **“公共”角色的限制架构：** 类型用户{ 名字：字符串！姓氏：字符串！ } 类型查询{ get_users_by_name（名字：字符串！，姓氏：字符串）：[用户] } **通过元数据 API：** POST /v1/元数据 HTTP/1.1 内容类型：application/json X-Hasura-角色：admin { “类型”：“add_remote_schema_permissions”， “参数”：{ "remote_schema": "user_api", “角色”：“公共”， “定义”：{ “schema”：“类型用户{名字：字符串！姓氏：字符串！}类型查询{get_users_by_name（名字：字符串！，姓氏：字符串）：[用户]}” } } } ### 远程模式参数预设自动将会话变量注入远程模式查询： **会话变量预设：** 类型查询{ get_user(id: ID!@preset(value: "x-hasura-user-id")): 用户 get_user_activities(user_id: ID!, limit: Int!): [活动] } **静态值预设：** 类型查询{ get_user(id: ID!@preset(value: "x-hasura-user-id")): 用户获取用户活动（ user_id：ID！限制：整数！ @预设（值：10） ): [活动] } **文字字符串（不是会话变量）：** 类型查询{ 你好（文本：字符串！@preset（值：“x-hasura-hello”，静态：true）） } ### 远程关系将本地数据库表连接到远程模式： **示例：将本地客户链接到远程支付 API** **SQL 表：** 创建表客户（ id 串行主键，名称文本不为空）； **远程架构（付款 API）：** 类型交易{ customer_id：整数！金额：整数！时间：字符串！商人：绳子！ } 类型查询{ transactions(customer_id: String!, limit: Int): [交易] } **远程关系定义：** - 表：姓名：客户模式：公共远程关系： - 名称：customer_transactions_history 定义：远程架构：付款哈苏拉字段： - 身份证号远程字段：交易：论点：客户 ID：$id **具有远程关系的 GraphQL 查询：** 查询{ 客户{ 姓名客户交易历史记录{ 金额时间 } } } ## 生产部署 ### Docker 部署 **docker-compose.yml：** 版本：'3.8' 服务： postgres：图片：postgres：15 重新启动：始终卷： - db_data:/var/lib/postgresql/data 环境： POSTGRES_PASSWORD：postgres密码健康检查：测试：[“CMD-SHELL”，“pg_isready -U postgres”] 间隔：10秒超时：5秒重试次数：5 哈苏拉：图片：hasura/graphql-engine:v2.36.0 端口： - “8080:8080” 取决于： postgres：条件：服务健康重新启动：始终环境： HASURA_GRAPHQL_DATABASE_URL：postgres://postgres:postgrespassword@postgres:5432/postgres HASURA_GRAPHQL_ENABLE_CONSOLE: "真" HASURA_GRAPHQL_DEV_MODE：“真” HASURA_GRAPHQL_ENABLED_LOG_TYPES：启动、http 日志、webhook 日志、websocket 日志、查询日志 HASURA_GRAPHQL_ADMIN_SECRET：myadminsecretkey HASURA_GRAPHQL_JWT_SECRET: '{"type":"HS256","key":"super-secret-jwt-signing-key-min-32-chars"}' HASURA_GRAPHQL_UNAUTHORIZED_ROLE：匿名卷：数据库数据： ### Kubernetes 部署 **hasura-deployment.yaml：** api版本：apps/v1 种类：部署元数据：姓名：哈苏拉命名空间：生产规格：副本：3 选择器：匹配标签：应用程序：哈苏拉模板：元数据：标签：应用程序：哈苏拉规格：容器： - 姓名：哈苏拉图片：hasura/graphql-engine:v2.36.0 端口： - 集装箱端口：8080 环境： - 名称：HASURA_GRAPHQL_DATABASE_URL 值来自：秘密密钥参考：名称：哈苏拉的秘密 key: 数据库-url - 名称：HASURA_GRAPHQL_ADMIN_SECRET 值来自：秘密密钥参考：名称：哈苏拉的秘密密钥：管理员秘密 - 名称：HASURA_GRAPHQL_JWT_SECRET 值来自：秘密密钥参考：名称：哈苏拉的秘密密钥：jwt-秘密 - 名称：HASURA_GRAPHQL_ENABLE_CONSOLE 值：“假” - 名称：HASURA_GRAPHQL_ENABLE_TELEMETRY 值：“假” 资源：要求：内存：“256Mi” 中央处理器：“100m” 限制：内存：“512Mi” 中央处理器：“500m” 活性探针： http获取：路径：/healthz 端口：8080 初始延迟秒数：30 周期秒：10 准备情况探针： http获取：路径：/healthz 端口：8080 初始延迟秒数：5 周期秒：5 --- api版本：v1 种类：服务元数据：姓名：哈苏拉命名空间：生产规格：类型：集群IP 选择器：应用程序：哈苏拉端口： - 端口：80 目标端口：8080 ### 环境变量（生产） **基本生产配置：** # 数据库 HASURA_GRAPHQL_DATABASE_URL=postgres://用户:密码@主机:5432/dbname # 安全 HASURA_GRAPHQL_ADMIN_SECRET=强随机秘密 HASURA_GRAPHQL_JWT_SECRET='{"type":"RS256","key":"..."}' HASURA_GRAPHQL_UNAUTHORIZED_ROLE=匿名 # 性能 HASURA_GRAPHQL_ENABLE_CONSOLE=false HASURA_GRAPHQL_DEV_MODE=false HASURA_GRAPHQL_ENABLE_TELEMETRY=false # 日志记录 HASURA_GRAPHQL_ENABLED_LOG_TYPES=启动、http-log、webhook-log、websocket-log # 速率限制 HASURA_GRAPHQL_RATE_LIMIT_PER_MINUTE=1000 # 跨域资源共享 HASURA_GRAPHQL_CORS_DOMAIN=https://myapp.com,https://admin.myapp.com # 连接数 HASURA_GRAPHQL_PG_CONNECTIONS=50 HASURA_GRAPHQL_PG_TIMEOUT=60 ### 监控和可观察性 **健康检查端点：** 卷曲 http://hasura:8080/healthz # 返回：确定 **普罗米修斯指标：** HASURA_GRAPHQL_ENABLE_METRICS=true HASURA_GRAPHQL_METRICS_SECRET=指标秘密 # 访问地址：http://hasura:8080/v1/metrics **结构化日志记录：** HASURA_GRAPHQL_ENABLED_LOG_TYPES=启动、http 日志、webhook 日志、websocket 日志、查询日志 HASURA_GRAPHQL_LOG_LEVEL=信息 **APM 集成（Datadog 示例）：** 环境： - 名称：HASURA_GRAPHQL_ENABLE_APM 值：“真” - 名称：DD_AGENT_HOST 值来自：字段参考：字段路径：status.hostIP - 名称：DD_SERVICE 值：“hasura-graphql” - 名称：DD_ENV 值：“生产” ## 迁移和版本控制 ### Hasura CLI 设置 **初始化Hasura项目：** hasura init my-project --endpoint https://hasura.myapp.com cd 我的项目 **项目结构：** 我的项目/ ├── config.yaml # Hasura CLI 配置 ├──metadata/ # 元数据文件 │ ├── 数据库/ │ │ └── 默认/ │ │ ├── 表格/ │ │ │ ├── public_users.yaml │ │ │ └── public_posts.yaml │ ├── actions.yaml │ ├──remote_schemas.yaml │ └── 版本.yaml └── migrations/ # 数据库迁移 └── 默认/ ├── 1642531200000_create_users_table/ │ └── up.sql └── 1642531300000_create_posts_table/ └── up.sql ### 创建迁移 **通过控制台（自动跟踪）：** # 启动带有迁移跟踪的控制台哈苏拉控制台 # 在控制台 UI 中进行更改 # 在migrations/文件夹中自动生成迁移 **手动迁移：** # 创建迁移 hasura migrate create create_users_table --database-name 默认 # 编辑生成的SQL文件 # 迁移/默认/{时间戳}_create_users_table/up.sql # 迁移/默认/{时间戳}_create_users_table/down.sql **迁移示例（up.sql）：** 创建表 public.users ( id UUID 主键默认 gen_random_uuid(), 电子邮件文本不为空唯一，用户名 TEXT NOT NULL UNIQUE, create_at TIMESTAMP NOT NULL DEFAULT NOW(), Updated_at TIMESTAMP NOT NULL DEFAULT NOW() ）；在 public.users(email) 上创建索引 idx_users_email; 创建索引 idx_users_username ON public.users(用户名); **迁移示例（down.sql）：** 如果存在则删除表 public.users CASCADE; ### 应用迁移 **应用迁移：** # 应用所有待处理的迁移 hasura migrate apply --database-name 默认 # 应用特定版本 hasura migrate apply --version 1642531200000 --database-name default # 检查迁移状态 hasura migrate status --database-name 默认值 ### 导出和导入元数据 **导出元数据：** Hasura 元数据导出 # 导出到元数据/文件夹 **应用元数据：** Hasura 元数据适用 # 应用元数据/文件夹中的元数据 **重新加载元数据：** Hasura 元数据重新加载 ### CI/CD 集成 **GitHub 操作示例：** 名称：部署哈苏拉于：推：分支：[主要] 职位：部署：运行：ubuntu-latest 步骤： - 使用：actions/checkout@v2 - 名称：安装 Hasura CLI 运行： | 卷曲-L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh |巴什 - 名称：应用迁移环境： HASURA_GRAPHQL_ENDPOINT：${{ Secrets.HASURA_ENDPOINT }} HASURA_GRAPHQL_ADMIN_SECRET：${{secrets.HASURA_ADMIN_SECRET }} 运行： | cd哈苏拉 hasura migrate apply --database-name 默认 Hasura 元数据适用 - 名称：重新加载元数据环境： HASURA_GRAPHQL_ENDPOINT：${{ Secrets.HASURA_ENDPOINT }} HASURA_GRAPHQL_ADMIN_SECRET：${{secrets.HASURA_ADMIN_SECRET }} 运行： | cd哈苏拉 Hasura 元数据重新加载 ## 最佳实践 ### 安全最佳实践 1. **在生产中始终使用 ADMIN_SECRET** * 切勿在未经身份验证的情况下公开管理 API *定期轮换秘密 * 使用强随机秘密（至少 32 个字符） 2. **实施适当的 JWT 验证** * 在生产中使用RS256（非对称） * 设置适当的令牌过期时间 * 验证发行者和受众的声明 3. **应用最低权限** * 从无访问权限开始，根据需要添加权限 * 对所有表使用行级安全性 * 对未经授权的角色隐藏敏感列 4. **在生产中禁用控制台** * `HASURA_GRAPHQL_ENABLE_CONSOLE=false` * 使用元数据文件和 CLI 进行更改 5. **启用速率限制** * 防止 DoS 攻击 * 如果需要，设置每个角色的限制 * 根据使用情况进行监控和调整 6. **验证 Webhook 有效负载** * 使用 webhook 秘密进行事件触发器 * 验证操作输入 * 清理所有用户输入 ### 性能最佳实践 1. **优化数据库查询** * 创建适当的索引 * 使用数据库视图进行复杂查询 * 利用 PostgreSQL 性能调优 2. **使用查询缓存** * 为昂贵的查询启用@cached指令 * 设置适当的TTL值 * 尽可能在 CDN 级别缓存 3. **限制查询深度和复杂性** * 设置最大查询深度限制 * 限制深度嵌套查询 * 对大型结果集使用分页 4. **配置连接池** * 调整`HASURA_GRAPHQL_PG_CONNECTIONS` * 监控连接使用情况 * 使用 PgBouncer 进行大型部署 5. **优化订阅** * 使用订阅复用 * 限制每个客户端的并发订阅数 * 考虑轮询时间敏感度较低的数据 ### 开发工作流程最佳实践 1. **版本控制元数据** * 将元数据/文件夹提交到 Git * 对所有架构更改使用迁移 * 查看 PR 中的元数据更改 2. **环境隔离** * 开发、暂存、生产环境 * 每个环境使用不同的管理密码 * 首先在暂存中测试迁移 3. **测试策略** * 彻底测试权限 * 集成测试事件触发器 * 独立测试动作处理程序 4. **文档** * 记录自定义操作及其输入/输出 * 解释复杂的权限规则 * 为消费者维护API文档 5. **监控和警报** * 监控查询性能 * 对失败的 webhook/事件触发器发出警报 * 跟踪错误率和延迟 ## 常见模式和示例 ### 模式 1：多租户 SaaS **架构：** 创建表组织（ id UUID 主键默认 gen_random_uuid(), 名称文本不为空）；创建表用户（ id UUID 主键默认 gen_random_uuid(), 电子邮件文本不为空唯一， organization_id UUID NOT NULL 引用组织（id））；创建表项目（ id UUID 主键默认 gen_random_uuid(), 名称文本不为空， organization_id UUID NOT NULL 引用组织（id））； **权限（用户表）：** { “过滤器”：{ “组织 ID”：{ "_eq": "X-Hasura-Org-Id" } } } **智威汤逊声明：** { “https://hasura.io/jwt/claims”：{ "x-hasura-default-role": "用户", "x-hasura-allowed-roles": ["用户", "组织管理员"], "x-hasura-user-id": "用户 uuid", "x-hasura-org-id": "org-uuid" } } ### 模式2：社交媒体应用 **架构：** 创建表用户（ id UUID 主键，用户名文本唯一非空，生物文本， avatar_url 文本）；创建表帖子（ id UUID 主键， user_id UUID 引用用户（id），内容文本不为空， is_public BOOLEAN 默认 true, 创建时间默认为 NOW() ）；创建表如下（ follower_id UUID 引用用户(id), follow_id UUID 引用用户（id），主键（follower_id、following_id））；创建表喜欢（ user_id UUID 引用用户（id）， post_id UUID 参考帖子(id), 主键（用户 ID、帖子 ID））； **权限：查看帖子（用户可以查看自己的帖子、公开帖子以及关注用户的帖子）：** { “过滤器”：{ “_或”：[ { “用户 ID”：{ "_eq": "X-Hasura-用户 ID" } }, { “是公共”：{ “_eq”：正确 } }, { “用户”：{ “关注者”：{ “follower_id”：{ "_eq": "X-Hasura-用户 ID" } } } } ] } } ### 模式三：电商平台 **架构：** 创建表产品（ id UUID 主键，名称文本不为空，价格 DECIMAL(10,2) NOT NULL, stock_quantity INT NOT NULL, is_active 布尔值默认 true ）；创建表订单（ id UUID 主键， user_id UUID NOT NULL, 状态文本不为空，总计 DECIMAL(10,2) NOT NULL, 创建时间默认为 NOW() ）；创建表 order_items ( id UUID 主键， order_id UUID 参考订单(id), Product_id UUID 参考产品(id), 数量 INT NOT NULL, 价格 DECIMAL(10,2) NOT NULL ）； **事件触发器：订单确认电子邮件** app.post('/webhooks/order-created', async (req, res) => { const { 事件 } = req.body; const order = event.data.new; // 获取订单详细信息和商品 const orderDetails =等待 fetchOrderDetails(order.id); // 发送确认邮件等待发送电子邮件({ 至：orderDetails.user.email，模板：'订单确认'，数据：订单详情 }); res.json({ 成功: true }); }); **行动：处理付款** 类型突变 { 流程付款( 订单ID：ID！ paymentMethodId：字符串！ ): 付款响应 } 类型付款响应{ 成功：布尔值！订单ID：ID！交易ID：字符串错误：字符串 } ### 模式 4：实时协作 **架构：** 创建表文档（ id UUID 主键，标题文本不为空，内容 JSONB NOT NULL DEFAULT '{}'::jsonb, 所有者 ID UUID 不为空， update_at TIMESTAMP DEFAULT NOW() ）；创建表 document_collaborators ( document_id UUID 参考文档（id）， user_id UUID NOT NULL, 权限 TEXT NOT NULL, -- '读', '写', '管理' 主键（文档 ID、用户 ID））； **权限：访问文档（自己的或协作的）：** { “过滤器”：{ “_或”：[ { “所有者 ID”：{ "_eq": "X-Hasura-用户 ID" } }, { “合作者”：{ “用户 ID”：{ "_eq": "X-Hasura-用户 ID" } } } ] } } **GraphQL订阅：实时更新** 订阅 DocumentUpdates($documentId: uuid!) { files_by_pk(id: $documentId) { 编号标题内容更新时间 } } ### 模式 5：带有分析功能的管理仪表板 **用于分析的自定义 SQL 函数：** 创建或替换函数 get_user_stats(user_row users) 退货表（帖子总数 INT, 粉丝总数 INT，总计以下 INT，参与率 DECIMAL ) 作为 $$ 选择 (SELECT COUNT(*) FROM posts WHERE user_id = user_row.id)::INT, (SELECT COUNT(*) FROM follow WHERE following_id = user_row.id)::INT, (SELECT COUNT(*) FROM 遵循 WHERE follower_id = user_row.id)::INT, (从帖子中选择 AVG(like_count)，其中 user_id = user_row.id)::DECIMAL $$ 语言 SQL 稳定； **Hasura 中的追踪功能：** - 功能：名称：获取用户统计信息模式：公共配置：自定义根字段：功能：获取用户统计信息 **GraphQL 查询：** 查询 UserWithStats { 用户{ 编号用户名获取用户统计信息{ 帖子总数粉丝总数总计关注参与率 } } } ## 故障排除 ### 常见问题和解决方案 **问题：JWT 验证失败** 解决方案： 1. 验证 JWT 秘密配置与您的身份验证提供商匹配 2. 检查 JWT 是否包含必需的 Hasura 声明 3. 确保声明位于正确的命名空间中 (https://hasura.io/jwt/claims) 4. 验证 JWT 尚未过期 5. 检查发行者和受众（如果已配置） **问题：权限被拒绝错误** 解决方案： 1. 检查角色是否在 allowed_roles 中 2.验证权限规则是否允许操作 3. 使用管理员角色进行测试以隔离权限问题 4. 检查会话变量是否正确发送 5. 查看行级和列级权限 **问题：事件触发器未触发** 解决方案： 1. 检查 webhook 是否可以从 Hasura 访问 2. 验证表名和操作是否匹配触发器配置 3.检查webhook返回200状态 4. 在 Hasura 控制台中查看事件触发日志 5. 确保数据库触发器已启用 **问题：操作返回错误** 解决方案： 1. 验证操作处理程序 URL 是否可访问 2. 检查请求/响应格式是否与操作定义匹配 3. 查看操作处理程序日志 4. 独立测试action handler 5. 验证权限允许角色执行操作 **问题：远程架构未加载** 解决方案： 1. 验证远程 GraphQL 端点是否可访问 2. 如果需要，检查身份验证标头 3. 独立测试远程模式 4. 检查超时设置 5. 检查类型名称冲突 **问题：订阅连接丢失** 解决方案： 1.检查托管平台上的WebSocket支持 2. 验证连接超时设置 3.在客户端实现重连逻辑 4. 检查防火墙/代理是否阻止 WebSocket 5. 监控连接池限制 ## 其他资源 ### 官方文档 * Hasura 文档： * Hasura GraphQL API 参考： * 哈苏拉云： ### 学习资源 * Hasura 学习： * Hasura 博客： * Hasura YouTube： ### 社区 *不和谐： * GitHub： * 论坛： ### 工具和集成 * Hasura CLI： * Hasura 云控制台： * GraphQL 代码生成器： ** ** **技能版本**：1.0.0 **最后更新**：2025 年 1 月 **技能类别**：后端、GraphQL、API 开发、实时、数据库 **兼容**：PostgreSQL、Auth0、Firebase、Cognito、Kubernetes、Docker

Hasura Graphql 引擎

包含技能