# @antelopejs/api 中文文档

规范地址：https://npmcn.com/package/%40antelopejs/api/

版本：1\.7\.0
npm 元数据更新时间：2026-11-04T21:15:02.251Z
中文译文更新时间：2026-11-06T06:28:49.776Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40antelopejs/api
原文对照：https://npmcn.com/package/%40antelopejs/api/?lang=original
项目主页：https://interfaces.antelopejs.com/docs/api/introduction
源码仓库：https://github.com/AntelopeJS/api

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：401 kB，108 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：@antelopejs/core \>=1\.17\.0 \<2
- 首次发布：2025-05-08T22:48:29.127Z
- 最新版本发布：2026-11-04T21:15:01.880Z
- 近 30 天下载量：5809（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 26 个）

## 中文简介

HTTP和AntelopeJS的WebSocket服务器模块,执行与Node.js http, https和ws服务器的API接口

## 安装

```sh
npm install @antelopejs/api
```

也可以使用：`pnpm add @antelopejs/api`、`yarn add @antelopejs/api`、`bun add @antelopejs/api`

## README

# `@antelopejs/api`

[![npm](https://img.shields.io/npm/v/@antelopejs/api?style=for-the-badge&labelColor=000000&color=000000)](https://www.npmjs.com/package/@antelopejs/api) [![License](https://img.shields.io/npm/l/@antelopejs/api?style=for-the-badge&labelColor=000000&color=000000)](https://npmcn.com/package/%40antelopejs/api/LICENSE) [![Discord](https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000)](https://discord.gg/g4pFt6eXqu) [![Documentation](https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000)](https://interfaces.antelopejs.com/docs/api/introduction)

羚羊JS的HTTP和WebSocket服务器模块. 它执行节点上的 API 接口 `http`, (中文(简体) ), `https`,以及 `ws` 服务器,因此控制器和其他模块以 `@antelopejs/interface-api` 回答请求.

部分 [羚羊JS](https://github.com/AntelopeJS/antelopejs)用于 [羚羊JS 隐形物](https://github.com/AntelopeJS/dms),用于您的 PostgreSQL 、 MongoDB 或 RethinkDB 数据库的开源后台.

## 接口

| 接口 | 文档 |
| --- | --- |
| [`@antelopejs/interface-api`](https://github.com/AntelopeJS/interface-api) | [API 密码](https://interfaces.antelopejs.com/docs/api/introduction) |
| [`@antelopejs/interface-api-util`](https://github.com/AntelopeJS/interface-api-util) | [API UTI 软件](https://interfaces.antelopejs.com/docs/api-util/introduction) |

界面页面文档控制器,路由,参数注入,前缀和后缀处理器,以及WebSocket处理器.

## 安装

```bash
ajs project modules add @antelopejs/api
```

命令写入模块的默认配置, 该配置是一个 HTTP 服务器 `localhost:8080`。在一个模块导入的项目中 `@antelopejs/interface-api`, (中文(简体) ), `ajs project modules install` 当还没有执行接口时,也添加了此模块.

## 配置

```typescript
import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    api: {
      source: {
        type: "package",
        package: "@antelopejs/api",
        version: "^1.3.4",
      },
      config: {
        servers: [
          { protocol: "http", host: "localhost", port: 8080 },
          { protocol: "https", port: 8443, cert: "<pem>", key: "<pem>" },
        ],
        publicBaseUrl: "https://api.example.com",
        strictPort: false,
        autoListen: true,
        cors: {
          allowedOrigins: ["https://app.example.com", /\.example\.com$/],
          allowedMethods: ["GET", "POST", "PUT", "DELETE"],
          allowedHeaders: ["content-type", "authorization"],
          credentials: true,
          maxAge: 600,
        },
      },
    },
  },
});
```

| 密钥 | 默认 | 说明 |
| --- | --- | --- |
| `servers` | 端口上的一个 HTTP 服务器 `80` | 服务器要启动 。 每个条目都使用 `protocol` (单位:千美元)`http` 或者说 `https`),可选 `host` 财务报告和审定财务报表 `port`,以及任何节点.js `http.ServerOptions` 或者说 `https.ServerOptions`。 。 。 . |
| `publicBaseUrl` | `API_LOCAL_BASE_URL` 单位: dev | 浏览器用来到达API的出处. 需要外出开发,没有它,靴子就失效了. |
| `strictPort` | `false` | 在开发中,失败而不是倒回下一个自由港. 外出开发,模块总是将准确的端口绑起. |
| `autoListen` | `true` | 设定为 `false` 创建服务器,并仅在模块调用时为服务器服务 `Listen()`。 。 。 . |
| `cors` | 无 | 中央统计局政策. `allowedMethods` 默认为 `GET,HEAD,PUT,PATCH,POST,DELETE`,以及 `credentials` 默认为 `true`。在运行时修改它 `SetCorsConfig()`。 。 。 . |

在开发中,回回回回回回源(C`localhost`, (中文(简体) ), `127.0.0.1`, (中文(简体) ), `[::1]`,任何端口)通过 CORS 不配置。 列出所有其它来源 `allowedOrigins`。 。 。 .

### 配置变量

该单元出版三部 [配置变量](https://framework.antelopejs.com/docs/concepts/configuration#module-config-variables)每个都来自第一个条目: `servers`。其他模块用 `${@api.<NAME>}`时 `api` 是模块的密钥在 `modules`。 。 。 .

| 变量 | 数值 |
| --- | --- |
| `API_PORT` | 第一个服务器绑定的端口 . |
| `API_LOCAL_BASE_URL` | 例如,同一宿主的起源 `http://127.0.0.1:8080`。 。 。 . |
| `API_PUBLIC_BASE_URL` | `publicBaseUrl`,没有跟踪鞭打. |

```typescript
modules: {
  "file-storage-local": {
    config: { baseUrl: "${@api.API_PUBLIC_BASE_URL}" },
  },
},
```

模块在任何其他模块构建之前绑定其收听套接字,所以 `API_PORT` 总是服务器服务的端口.

软件包命名了计算它们的函数, `configVars` 内 `dist/config-vars.js`输入 `antelopeJs.configVarsFile`。读取项目而不运行它的工具,例如 `ajs dms build`,解决 `${@api.<NAME>}` 与该功能。 这样的话 `API_PORT` 是配置的端口,并且 `API_PUBLIC_BASE_URL` 倒计时 `API_LOCAL_BASE_URL` 何时 `publicBaseUrl` 未设置.

### 启动门

该模块为端口服务 `construct` 继续 在核心宣布每个模块都开始之前,它用 `503`,躯体 `error.server_starting`,以及 `Retry-After: 1`。 。 。 . `@antelopejs/core` 发送通知为 `Events.ModulesStarted` 联 合 国 `@antelopejs/interface-core/modules`当整个项目在停工时停止(`Events.ModulesStopping`),模块答案 `503` 再来一次 停止,重新装入,或者在运行时移除单个模块会让出出门.

发射时未能启动的模块离开项目答案 `503`。同样 `start()` 120秒后仍未解决 导致启动失败 门所持请求没有运行,所以客户端可以重试. 模块在门关上时回答 CORS 预飞, 因此浏览器可以读取 `503`。 。 。 .

`GET /_live` 总是回答 `200`用它做活性探测器 用正常路线做准备探测器.

## 快开始

在服务路线的模块中,添加接口.

```bash
pnpm add @antelopejs/interface-api
```

在模块条目中宣布一个控制器 。 它的装饰器在模块装入时会登记路径.

```typescript
import { Controller, Get, Parameter } from "@antelopejs/interface-api";

export class HelloController extends Controller("/greetings") {
  @Get()
  hello(@Parameter("name", "query") name = "world") {
    return { message: `Hello ${name}` };
  }
}

export function construct(): void {}
export function destroy(): void {}
export function start(): void {}
export function stop(): void {}
```

`@Get()` 没有位置使用方法名称,所以路由是 `/greetings/hello`。运行项目时使用 `ajs project dev`,然后调用 `GET http://localhost:8080/greetings/hello?name=Ada`。 。 。 .

## 文档

-   [API 密码](https://interfaces.antelopejs.com/docs/api/introduction) 文档 `@antelopejs/interface-api` 与本模块执行的合同.
-   [API UTI 软件](https://interfaces.antelopejs.com/docs/api-util/introduction) 文档 `@antelopejs/interface-api-util` 与本模块执行的合同.
-   [配置](https://framework.antelopejs.com/docs/concepts/configuration) 文档模块来源, `config` 区块和配置变量 `antelope.config.ts`。 。 。 .

## 兼容性

| 软件包 | 支助 | 测试过 |
| --- | --- | --- |
| `@antelopejs/core` | `>=1.17.0 <2` | `1.20.0` |
| `@antelopejs/interface-api` | `>=0.2.0 <0.4.0` | `0.2.0` |
| `@antelopejs/interface-api-util` | `>=0.3.0 <1.0.0` | `0.3.0` |
| `@antelopejs/interface-core` | `>=0.4.0 <1.0.0` | `0.4.0` |

生成的表格列表 `@antelopejs/core`,该模块要求作为对等依赖的模块,以及它所加载的接口包,其范围从 `package.json`。如果另一个已装入的模块宣布一个排除本模块载重复制范围, `@antelopejs/core` 拒绝启动项目。 报告 `Incompatible interface package resolution` 并命名模块、其范围及其找到的副本.

## 捐款

```bash
pnpm install
pnpm dev            # run the playground/ project in watch mode
pnpm lint
pnpm format:check
pnpm knip
pnpm test           # build, then ajs module test
```

读取 [捐款准则](https://npmcn.com/package/%40antelopejs/api/CONTRIBUTING.md) 在打开拉出请求之前.

## 许可证

[阿帕奇 - 2.0](https://npmcn.com/package/%40antelopejs/api/LICENSE)

## 常见问题

### @antelopejs/api 是什么？

HTTP和AntelopeJS的WebSocket服务器模块,执行与Node\.js http, https和ws服务器的API接口

### 如何安装 @antelopejs/api？

在项目目录运行 npm install @antelopejs/api，或使用 pnpm add / yarn add / bun add。

### @antelopejs/api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @antelopejs/api 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @antelopejs/api 可以商用吗？

@antelopejs/api 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @antelopejs/api 的下载量有多少？

根据 npm 官方下载统计，@antelopejs/api 在 2026/10/06 – 2026/11/04 这 30 天内被下载 5,809 次，日均约 194 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @antelopejs/api 还在维护吗？

最新版本 1\.7\.0 发布于 2026/11/05（1 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 26 个；首次发布于 2025/05/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。