通过

在数据 API 生成器中使用 @env() 进行环境变量替换

数据 API 生成器（DAB）通过在加载时替换值让您将机密（例如数据库连接字符串）保留在dab-config.json之外。 第一种受支持的机制是 @env() 函数，它从主机进程环境或本地 .env 文件解析环境变量。

另请参阅： the @akv() function.

什么是@env()的功能

在预期字符串值的任何位置放置对环境变量的引用：

{
  "data-source": {
    "connection-string": "@env('SQL_CONN_STRING')"
  }
}

在配置加载时，DAB 会扫描匹配 @env('VAR_NAME') 模式的字符串，并将该标记替换为环境变量 VAR_NAME 的值。

数值来源

来源 Description
OS/进程环境 DAB 进程启动时存在的标准环境变量。
.env 文件 配置目录中带有 NAME=VALUE 行的纯文本文件（为方便本地开发）。

注释

当两者都定义相同的名称时，该文件 .env 将替代现有进程/系统环境变量。 如果您提供用于开发的本地 .env 文件，则其条目将用于满足 @env( 'var-name' 查找，而无需对本地环境进行调用。

示例 .env 文件：

SQL_CONN_STRING=Server=localhost;Database=AppDb;User Id=app;Password=local-dev;
DB_TYPE=mssql
JOB_API_KEY=dev-job-key

指引：

  • 保持 .env 紧邻 dab-config.json（或放置在启动进程所需的任何位置）。
  • 已将 .env 添加到 .gitignore。
  • 通常情况下，以#开头的空行和其他行会被忽略（如果支持该功能，请验证）；在记录注释支持之前进行确认。
  • 在 Linux/macOS 上，名称区分大小写。 在 Windows 上，它们实际上不区分大小写。

在 @env() 配置中使用

基本替换

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@env('SQL_CONN_STRING')"
  }
}

与 @akv()

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@akv('prod-sql-connection')"
  }
}

存储过程参数

{
  "entities": {
    "RunJob": {
      "source": {
        "object": "dbo.RunJob",
        "type": "stored-procedure",
        "parameters": {
          "intParam": "@env('SP_PARAM1_INT')",
          "boolParam": "@env('SP_PARAM2_BOOL')"
        }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ "execute" ] }
      ]
    }
  }
}

环境值被替换为字符串。 随后的解析（例如转换为 int 或 bool）由使用方的配置或运行时逻辑处理。

Troubleshooting

Scenario 结果
找到变量 替换成功。
变量不存在 配置加载可能失败。
找不到变量 替换为空字符串。
不同属性中的多个@env() 所有已独立解决。
用于需要数值或布尔值的位置 值已替换成字符串；解析可能成功。
无效模式（例如 @env(DB_VAR) 缺少引号） 被视为文本字符串。

完整示例

dab-config.json:

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@env('SQL_CONN_STRING')"
  },
  "runtime": {
    "rest": { "enabled": true }
  },
  "entities": {
    "Books": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

.env:

DB_TYPE=mssql
SQL_CONN_STRING=Server=localhost;Database=BooksDb;User Id=app;Password=StrongPassword!;

重要

不要提交 .env 包含机密的文件。 |

快速参考

Item 概要
Syntax @env('variable-name')
模拟文件 .env 带有 name=value 行
混合 @env() 支持.

Review

使用 @env() 将机密和环境特定的值排除在配置文件之外。 将其与规则机密管理（例如 CI/CD 变量存储或容器定义）配对，以便进行安全灵活的部署。 对于企业保管库，请结合@akv()功能整合机密。