# @flexent/http-server 中文文档

规范地址：https://npmcn.com/package/%40flexent/http-server/

版本：2\.22\.1
npm 元数据更新时间：2026-11-13T14:15:48.565Z
中文译文更新时间：2026-11-14T22:40:42.472Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40flexent/http-server
原文对照：https://npmcn.com/package/%40flexent/http-server/?lang=original

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

- 包体积（解压后）：75.9 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：mesh-ioc ^4\.3\.1，nanoevent ^1\.0\.0，mesh-config ^1\.3\.4，@flexent/errors ^2\.22\.1，@flexent/logger ^2\.22\.1，mesh-decorators ^1\.3\.6，@flexent/metrics ^2\.22\.1，@flexent/pathmatcher ^2\.22\.1
- 首次发布：2022-09-27T15:50:16.978Z
- 最新版本发布：2026-11-13T14:15:48.404Z
- 近 30 天下载量：2522（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：71（近 12 个月 40 个）

## 中文简介

平庸的 HTTP 服务器 API

## 安装

```sh
npm install @flexent/http-server
```

也可以使用：`pnpm add @flexent/http-server`、`yarn add @flexent/http-server`、`bun add @flexent/http-server`

## README

# @flexent/http-server (英语)

**状态:α. 积极发展,出新出会打破事物.**

最小 Http 服务器,基于 [网间网络](https://github.com/MeshIoC/mesh-ioc)。 。 。 .

## 要点

-   最小抽象度高于本地API
-   ++可编译处理器
-   \* 包括(但未执行)标准处理人员

## 使用量

### 处理器

应用逻辑在HTTP处理器中被执行. 每个处理器处理其子集域,代表通过调用下()处理给其他人.

```ts
export class FooHandler extends HttpHandler {

    async handle(ctx: HttpContext, next: HttpNext) {
        // Call next() to execute the next middleware in chain.
        // Or assign ctx.status and ctx.responseBody to end request processing
    }

}
```

处理器可以从 `async (ctx: HttpContext, next: HttpNext) => Promise<void>` 函数 :

```ts
const handler = createHandler(async (ctx: HttpContext, next: HttpNext) => {
    ctx.status = 200;
    ctx.responseBody = 'Hello, world!';
}); // returns HttpHandler
```

### 链条

多个处理器组成了链.

链条也是处理器,因此请求处理可以是分级的.

```ts
export class AppHandler extends HttpChain {

    @dep() private foo!: FooHandler;
    @dep() private bar!: BarHandler;
    @dep() private baz!: BarHandler;

    handlers = [
        this.foo,
        this.bar,
        this.baz,
    ];
}
```

还可以明确建立链条:

```ts
const chain = createChain([
    this.foo,
    this.bar,
    this.baz,
]); // returns HttpHandler
```

### Http 服务器

Http 服务器实例会听到请求,并将请求委托给一个处理器.

它的配置使用 `createScope` 它为每项请求创造了一个新的范围(网格实例)。 默认,它会解决 `HttpScope` 并授权处理 `HttpHandler` 从范围.

```ts
// Composition root (global scope)
mesh.service(HttpServer);
mesh.scope(HttpScope);
```

```ts
// Per-request scope
export class HttpScope {
    constructor(parent: Mesh) {
        super('Http', parent);
        this.service(HttpHandler, MyHandler);
    }
}
```

或者,可以直接在组成根中创建范围:

```ts
mesh.service(HttpServer);
mesh.scope('HttpScope', () => {
    const mesh = new Mesh('Http', mesh);
    mesh.service(HttpHandler, MyHandler);
    return mesh;
});
```

### 请求范围

大多数应用需要请求范围状态。 譬如说, `AuthHandler` 可以建立呼叫者的身份(例如通过读取信头、饼干、解析JWT等),并将此身份保存在 `AuthContext` 其他操作人员可以使用.

这样的话, `AuthContext` 并且其所有受抚养人都将被请求范围(即每个请求一个实例). 网格有助于这种范围界定.

一个最小的例子:

```ts
// scoped/AuthContext.ts
export class AuthContext {

    principal: User | null = null;

    setPrincipal(user: User) {
        this.user = user;
    }
}
```

```ts
// scoped/AuthHandler.ts
export class AuthHandler implements HttpHandler {

    @dep() private auth!: AuthContext;

    async handle(ctx: HttpContext, next: HttpNext) {
        const authorization = ctx.getRequestHeader('Authorization');
        const user = await this.authorize(authorization);
        this.auth.setPrincipal(user);
        await next();
    }
}
```

```ts
export class AppHandler extends HttpChain {

    @dep() private authHandler!: AuthHandler;
    @dep() private fooHandler!: FooHandler;

    handlers = [
        this.authHandler,
        this.fooHandler,
    ];
}
```

```ts
export class HttpScope extends Mesh {
    constructor(parent: Mesh) {
        super('Http', parent);
        this.service(AuthContext);
        this.service(AuthHandler);
        this.service(FooHandler);
        this.constant(HttpHandler, AppHandler);
    }
}
```

## 配置

Http 服务器默认支持以下env变量:

-   HTTP Port( 默认值: 8080) - 要收听的端口
-   HTTP ADADSES( 默认为 0.0. 0.0 ) - 绑定地址
-   HTTP TIMEOUT( 默认: 300 000 }) - HTTP 套接字超时
-   HTTP SHUTDOWN DELAY( 默认 : 5 000 }) —— 停止接受连接前的睡眠( 用于在 k8s 等环境中的 0- 下行部署)
-   HTTP BODY LIMIT (默认: 5 \* 1024 \* 1024 }) - 请求正文中允许的最大字节数

## API 计费表

### 请求

#### 请求 URL

请求 URL 已解析并可作为本地 `URL` 对象 :

```ts
ctx.url.searchParams;
```

#### 查询参数

使用 `ctx.url.searchParams` 访问查询字符串.

或者,使用 `ctx.query` 是一个 [Http 密码](https://npmcn.com/package/%40flexent/http-server/#readme-http-dict)。 。 。 .

#### 请求信头

获取请求头值 :

```ts
const authorization = ctx.getRequestHeader('Authorization');
```

请求信头支持多个值,所以存储为 [Http 密码](https://npmcn.com/package/%40flexent/http-server/#readme-http-dict)。 。 。 .

```ts
ctx.requestHeaders; // { 'content-type': ['application/json'], ... }
```

#### 请求机构

请求体需要明确读取.

```ts
const body = await ctx.readRequestBody();
```

体型推断自 `Content-Type` 头,但也可以明确指定.

```ts
const jsonBody = await ctx.readRequestBody('json');
```

下列请求体类型得到支持:

-   `json`
-   `text`
-   `urlencoded`
-   `raw`

### 回应

#### 身份代码

指定状态代码 :

```ts
ctx.status = 500;
```

状态也可以从标准Middleware所抛出的错误中读取:

```ts
class AccessDeniedError extends Error {
    status = 403;
    override name = this.constructor.name;
}

throw new AccessDeniedError();
```

#### 答复信头

设置响应头值 :

```ts
ctx.setResponseHeader('X-Powered-By', 'My Awesome App');
```

响应信头支持多个值,因此存储为 [Http 密码](https://npmcn.com/package/%40flexent/http-server/#readme-http-dict)。 。 。 .

#### 反应机构

设定响应机构 :

```ts
ctx.responseBody = {
    foo: 123
};
```

这个 `Content-Type` 财务报告和审定财务报表 `Content-Length` 如果不明确预测,则会推断出信头.

支持以下应对机构类型:

-   字符串( 文本/ 平面)
-   JSON(应用/json)
-   缓冲(应用/x-octet-stream)
-   流( 默认用块编码接通)

注意: 如果您正在使用缓冲或流线, 您可能希望明确设置 Content- Type .

### 杂项

#### Http 密码

请求/响应信头和解析的查询字符串对象支持每个密钥的多个值.

为了向它们提供统一的型号安全访问,它们被储存为 `HttpDict` 类型, 只不过 `Record<string, string[]>`。 。 。 .

因此在访问时期望字符串数组 `ctx.requestHeaders`, (中文(简体) ), `ctx.responseHeaders` 或者说 `ctx.query`。 。 。 . 或使用 `ctx.getRequestHeader`, (中文(简体) ), `ctx.setResponseHeader` 财务报告和审定财务报表 `ctx.url.searchParams` 高级API.

## 常见问题

### @flexent/http-server 是什么？

平庸的 HTTP 服务器 API

### 如何安装 @flexent/http-server？

在项目目录运行 npm install @flexent/http-server，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：mesh-ioc（^4\.3\.1）、nanoevent（^1\.0\.0）、mesh-config（^1\.3\.4）、@flexent/errors（^2\.22\.1）、@flexent/logger（^2\.22\.1）、mesh-decorators（^1\.3\.6）、@flexent/metrics（^2\.22\.1）、@flexent/pathmatcher（^2\.22\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flexent/http-server 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/flexent\_\_http-server 是否存在。

### @flexent/http-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @flexent/http-server 可以商用吗？

@flexent/http-server 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flexent/http-server 的下载量有多少？

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

### @flexent/http-server 还在维护吗？

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