artcom/acms-api

ACMS API 镜像文档

镜像概述和主要用途

ACMS API是一个JSON API服务，用于从Git仓库提供JSON文件内容。该服务要求仓库中的所有文件均为带.json扩展名的JSON文件，支持通过API接口获取、更新和删除仓库中的JSON内容，并提供变量替换功能。

核心功能和特性

• Git仓库集成：直接连接Git仓库，提供JSON文件内容的API访问
• 变量替换：支持通过环境变量替换JSON内容中的变量
• 完整的API操作：提供GET（获取）、PUT（更新）、DELETE（删除）等操作接口
• 版本控制：支持基于Git提交哈希或引用访问不同版本的内容
• 目录结构映射：将仓库目录结构映射为JSON对象层级结构

使用场景和适用范围

• 作为轻量级内容管理系统（CMS）后端，通过Git管理JSON格式内容
• 配置管理服务，集中管理应用配置文件
• 静态内容API服务，为前端应用提供结构化数据
• 需要版本化管理JSON数据的场景

配置说明

环境变量

服务使用以下环境变量进行配置：

• REPO_URI (必填)：Git仓库的URI
• SIGNATURE_MAIL (可选)：用于生成提交的电子邮件地址
• REPO_TOKEN (可选)：访问私有仓库的令牌
• ACMS_API_VAR_* (可选)：用于内容中变量替换的环境变量列表（详见"变量替换"）

变量替换

服务在提供和写入内容时会替换变量。所有变量需为前缀为ACMS_API_VAR_的环境变量。例如：

bash
export ACMS_API_VAR_MY_FANCY_VARIABLE="value"

如果内容中出现变量，将被替换为指定值。写入仓库时，值也会被替换为变量名。

示例：

内容:                          "Hello ${properGreeting}."  
ACMS_API_VAR_PROPER_GREETING:     "World"  
提供内容:                           "Hello World."

API接口说明

GET /:version

返回指定版本的仓库内容，作为单个JSON对象。版本可以是Git提交哈希或引用。响应头Git-Commit-Hash包含Git提交哈希。

返回对象包含仓库根目录中每个文件的内容（属性名为文件名，不带扩展名），目录则包含具有相同结构的子对象。

示例： 若仓库包含file1.json、file2.json、directory/fileA.json和directory/subDirectory/fileB.json，响应结构如下：

json5
// GET <url>/master
{
  "directory": {
    "fileA": {
      "foo": "bar"
    },
    "subDirectory": {
      "fileB": {
        "foo": "bar"
      }
    }
  },
  "file1": {
    "min": 1,
    "max": 10
  },
  "file2": [
    "item1",
    "item2",
    "item3"
  ]
}

GET /:version/path

可在前面路由基础上添加额外路径，以获取特定数据。

示例：

json5
// GET <url>/master/directory/fileA
{
  "foo": "bar"
}

GET /:version/path?listFiles=true

listFiles参数返回平面结构，包含path及其子目录中的所有文件，文件路径为键，文件内容为值。

示例：

json5
// GET <url>/master/directory?listFiles
{
  "file1": {
    "foo": "bar"
  },
  "file2": [1, 2, 3],
  "subDirectory/file3": "foo"
}

PUT /:version/path

使用PUT请求替换目录或单个文件的内容。请求体应包含所有文件和子目录的JSON数据或单个文件数据。建议工作流：使用GET /:version/path查询路径，修改数据后通过PUT /:parentVersion/path发送回完整数据。

将创建新的Git提交并在必要时合并。响应头Git-Commit-Hash包含新（合并）提交的哈希。合并失败将返回错误。

示例

替换目录内所有内容的请求体：

json5
// PUT <url>/master/directory
{
  "files": {
    "fileA": {
      "foo": "bar"
    },
    "subDirectory/fileB": {
      "foo": "bar"
    }
  }
}

仅替换单个文件的请求体：

json5
// PUT <url>/master/file1
{
  "fileContent": {
    "min": 10,
    "max": 30
  }
}

额外属性：

• author：提交作者
• updateBranch：应更新到新提交的分支（默认："master"）

DELETE /:version/path

使用DELETE请求删除目录或单个文件。请求体应包含JSON数据，包含file或directory属性。

将创建新的Git提交并在必要时合并。响应头Git-Commit-Hash包含新（合并）提交的哈希。合并失败将返回错误。

示例

删除单个文件：

json5
// DELETE <url>/master/parentDirectory
{
  "file": "fileToDelete"
}

删除目录：

json5
// DELETE <url>/master/parentDirectory
{
  "directory": "directoryToDelete"
}

额外属性：

• author：提交作者
• updateBranch：应更新到新提交的分支（默认："master"）

开发设置

bash
npm install
REPO_URI=<仓库URL> npm run watch

部署说明

Heroku/Dokku

该服务设计用于通过Dokku部署，也可能适用于Heroku及其他兼容平台。

Docker部署

服务包含Dockerfile，可直接通过Docker启动。

Docker run示例：

bash
docker run -d \
  -e REPO_URI=https://github.com/yourusername/your-repo.git \
  -e ACMS_API_VAR_MY_VAR=value \
  -p 3000:3000 \
  --name acms-api \
  acms-api-image

故障排除

在Mac OS上，若使用Node 16运行npm install时遇到错误：error: no template named 'remove_cv_t' in namespace 'std'; did you mean 'remove_cv'?，尝试：

bash
export CXXFLAGS="--std=c++17" && npm install

（参见node-gyp https://github.com/nodejs/node-gyp/issues/2387%EF%BC%89