通过

使用运行状况检查和运行状况终结点

数据 API 生成器提供一个 /health 终结点，用于监视 API 数据源和实体的响应能力和运行状况。 此终结点针对配置的数据源和实体运行检查，验证它们是否在设置的阈值内做出响应。

运行状况检查的工作原理

  • 对于每个数据源，一个简单的特定于数据库的查询会验证连接性并测量响应时间。
  • 对于启用了 REST 或 GraphQL 的每个实体，查询返回前 N 行以确认响应能力。
  • 存储过程会自动从运行状况检查中排除，因为它们需要参数，可能不是确定性的。
  • 终结点 /health 将这些结果聚合为指示总体运行状况的综合报告。

运行时健康配置

健康检查在 runtime.health 部分受到控制：

{
  "runtime": {
    "health": {
      "enabled": true,
      "roles": ["admin", "monitoring"],
      "cache-ttl-seconds": 10,
      "max-query-parallelism": 4
    }
  }
}
资产 类型 违约 DESCRIPTION
enabled 布尔 是 全局启用或禁用综合健康状态端点
roles 字符串[] null 允许访问 /health 终结点的角色
cache-ttl-seconds 整数 5 缓存健康报告的生存期（以秒为单位）
max-query-parallelism（最大查询并行度） 整数 4 最大并发运行状况检查请求数量（范围：1-8）

基于角色的访问行为

  • 开发模式（host.mode: development）：

    • 未配置roles时：运行状况终结点可供所有用户访问(视为匿名)
    • 当 roles 被配置时，只有指定的角色才能访问终结点。

  • 生产模式（host.mode: production）：

    • roles 必须显式定义
    • 省略 roles 对所有请求返回 403 禁止
    • 若要允许公共访问，请设置 "roles": ["anonymous"]

重要

此处配置的角色控制对健康检查端点的访问，而不是控制单个实体操作的权限。 如果角色缺少查询实体的权限，该实体的运行状况检查将反映失败，这是预期行为。

根路径上的基本健康检查终结点

简化的运行状况终结点 / 始终可公开访问，无需身份验证。 它返回基本服务信息（版本、状态），而无需运行任何运行状况检查。

数据源健康状况配置

每个数据源都可以配置为执行data-source.health健康检查：

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 1500
    }
  }
}
资产 类型 违约 DESCRIPTION
enabled 布尔 是 为此数据源启用健康检查
姓名 字符串 database-type 值 运行状况报告中显示的唯一标识符
阈值-ms (阈值以毫秒为单位) 整数 1000 允许的最大查询执行时间（以毫秒为单位）

实体健康状态配置

可以在以下项中 entities.{entity-name}.health为每个实体启用实体检查：

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 50,
        "threshold-ms": 500
      }
    }
  }
}
资产 类型 违约 DESCRIPTION
enabled 布尔 是 为实体启用运行状况检查
第一 整数 100 运行状况查询返回的行数（范围：1-500）
threshold-ms 整数 1000 允许的最大查询执行时间（以毫秒为单位）

注释

的值 first 必须小于或等于运行时 max-page-size配置。 较小的 first 值可提高性能。 监视多个实体时，较高的 first 值可能会降低报表速度。

如果启用了 REST 和 GraphQL，则运行实体运行状况检查。 每个条目都显示为报表中带有标记（rest 或 graphql） 的单独条目。

性能和缓存注意事项

运行状况检查缓存 （cache-ttl-seconds）：

  • 防止快速请求压倒系统
  • 缓存已配置的 TTL 的完整运行状况报告
  • 将0设置为禁用缓存。
  • 默认值：5 秒

查询并行度 （max-query-parallelism）：

  • 控制并发运行的健康检查查询数量
  • 较高的值可加快检查速度，但增加数据库负载
  • 范围：1-8
  • 默认值：4
  • 如果有多个实体或严格的资源限制，请使用较低的值

示例健康检查响应

{
  "status": "Healthy",
  "version": "1.2.3",
  "app-name": "dab_oss_1.2.3",
  "timestamp": "2025-01-15T10:30:00Z",
  "configuration": {
    "rest": true,
    "graphql": true,
    "mcp": true,
    "caching": false,
    "telemetry": true,
    "mode": "Production"
  },
  "checks": [
    {
      "status": "Healthy",
      "name": "primary-sql-db",
      "tags": ["data-source"],
      "data": {
        "response-ms": 12,
        "threshold-ms": 1500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["rest", "endpoint"],
      "data": {
        "response-ms": 45,
        "threshold-ms": 500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["graphql", "endpoint"],
      "data": {
        "response-ms": 38,
        "threshold-ms": 500
      }
    }
  ]
}

其他注意事项

  • 运行状况检查遵循实体和终结点的授权机制。 如果角色缺少访问实体的权限，系统健康检查会报告此问题。
  • 存储过程被排除，因为它们需要参数，并且可能会产生副作用。
  • 具有 rest.enabled: false 或 graphql.enabled: false 的实体不在这些检查范围内。
  • data-source.health.enabled: false 时将跳过数据源检查。
  • Last updated on