# @data-fair/lib-express 中文文档

规范地址：https://npmcn.com/package/%40data-fair/lib-express/

版本：2\.0\.0
npm 元数据更新时间：2026-10-29T15:44:07.206Z
中文译文更新时间：2026-11-14T16:50:59.471Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40data-fair/lib-express
原文对照：https://npmcn.com/package/%40data-fair/lib-express/?lang=original

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

- 包体积（解压后）：405 kB，80 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：ws 8，express 5，@data-fair/lib-node ^3\.0\.0
- 首次发布：2024-10-08T08:14:21.665Z
- 最新版本发布：2026-10-29T15:43:58.279Z
- 近 30 天下载量：1975（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 26 个）

## 中文简介

与数据公平堆栈中Express的使用相關的中相器和公用功能.

## 安装

```sh
npm install @data-fair/lib-express
```

也可以使用：`pnpm add @data-fair/lib-express`、`yarn add @data-fair/lib-express`、`bun add @data-fair/lib-express`

## README

# @ data-fair/ lib- express

由数据公平堆栈的网络服务共享的快取 5 个中间软件和帮助器:会话读取,错误处理,反向代理意识请求信息,SPA服务,websocket服务器,身份webhooks.

## 安装

```sh
npm i @data-fair/lib-express @data-fair/lib-node express
```

同伴依赖性 : `@data-fair/lib-node@^3.0.0`, (中文(简体) ), `express@5`,以及 `ws@8` (可选,仅限 `ws-server.js`) (中文(简体) ).

## 模块

| 导入路径 | 说明 |
| --- | --- |
| `@data-fair/lib-express` | 再出口小的普通棋子: `session.js`, (中文(简体) ), `errorHandler`找到乌提尔斯, `httpError`, (中文(简体) ), `req-origin.js`, (中文(简体) ), `site.js`, (中文(简体) ), `serve-spa.js`。 。 。 . |
| `@data-fair/lib-express/session.js` | `session` 验证简单的指令片段饼干, `session.middleware()` (也打开请求日志上下文,参见 `@data-fair/lib-node/log.js`, (中文(简体) ), `reqSession()` 编号 : `reqSessionAuthenticated()` 编号 : `reqAdminMode()` 进入者. |
| `@data-fair/lib-express/error-handler.js` | Express 错误处理器: 将错误映射到状态代码, 日志 5xx 作为错误, 401/403 作为警告, 当隐藏 5xx 细节时 `NODE_ENV=production`。 。 。 . |
| `@data-fair/lib-express/req-origin.js` | 反向代理意识请求信息 : `reqOrigin()`, (中文(简体) ), `reqHost()`, (中文(简体) ), `reqIp()`, (中文(简体) ), `reqIsInternal()`, (中文(简体) ), `assertReqInternalSecret()`, (中文(简体) ), `secretKeyMatches()`. |
| `@data-fair/lib-express/site.js` | `createSiteMiddleware(servicePathPart)`:取出请求的站点路径前缀, `reqSitePath()`, (中文(简体) ), `reqSiteUrl()`。 。 。 . |
| `@data-fair/lib-express/serve-spa.js` | `createSpaMiddleware()`:服务于已建成的有UI配置注入,缓存头和CSP的SP. |
| `@data-fair/lib-express/find-utils.js` | `mongoSort()`, (中文(简体) ), `mongoPagination()`, (中文(简体) ), `mongoProjection()` 从查询参数. |
| `@data-fair/lib-express/req-perf.js` | 按路线排列的 `df_req_step_seconds` 直方图. |
| `@data-fair/lib-express/ws-server.js` | 有频道订阅的 Websocket 服务器, 由 `@data-fair/lib-node/ws-emitter.js`。 。 。 . |
| `@data-fair/lib-express/identities/index.js` | `createIdentitiesRouter()`: 接收简单指令中的身份网点. |
| `@data-fair/lib-express/async-handler.js` | 被折旧:快车5号在本土处理Aync路线. |

## 会议

会议宣读 `id_token` 饼干由简单的目录设定,用它的JWKS验证. 以简单目录的 URL 初始化, 然后应用中间软件 :

```ts
import express from 'express'
import { session, reqSessionAuthenticated, errorHandler } from '@data-fair/lib-express'

session.init(config.privateDirectoryUrl)

const app = express()
app.use('/api', session.middleware()) // or { required: true }, { adminOnly: true }

app.get('/api/items', async (req, res) => {
  const { account, accountRole } = reqSessionAuthenticated(req) // 401 if not authenticated
  // ...
})

app.use(errorHandler)
```

权限、 账户角色、 管理模式和 Vue 侧被覆盖 [`data-fair-session` 技能](https://github.com/data-fair/lib/tree/main/skills/data-fair-session)。 。 。 .

### 范围和无记名证

-   `Authorization: Bearer <token>` 在饼干之前读取,然后从不读取。 一个标志 JWT 标题 `typ: at+jwt` 任何失败都是401 任何其他 无记名者(空出, API 密钥, 会话符号, 另一系统符号) 不自称为 : 请求是匿名的.
-   带有一个符号 `scope` 索赔额 `sessionState.scopes` (非字符串索赔为401起)。 一个服务 执行范围呼叫 `session.init(directoryUrl, lang, onlyDecode, { scopeAware: true })`· ; 否则,每次限制范围的会议都会得到403分. `scopeAware` 自由节日也很荣幸 `SessionHandler` (单位:千美元)`readStateFromCookie` 编号 : `readStateFromBearer`所以消费者直接使用它 默认关闭.
-   进入信使最多携带一个组织成员(无 = 个人账户);信使 数个被拒绝 以401.
-   `requireScope('datasets:read')` 守住一条路 它通过下列方式解读会议内容: `session.reqWithScope(req, accepted)` (根据请求),所以不需要 `session.middleware()`。 。 。 . `assertReqScope(req, ...)` 是路线的同步变体 中间软件后面. `hasScope` 编号 : `assertScope` 做同样的代码。 无范围的会议是不受限制的. 诸如: `datasets` 已经覆盖 `datasets:read`,因此无需列出. "写意为已读"通过列出被接受的范围来表示,例如. `requireScope(['datasets:read', 'datasets:write'])` (其中任何一个都足够). 创建这些列表 `defineScopes` 联 合 国 `@data-fair/lib-common-types/scopes.js` 而不是通过 手:它增加了保护伞和全球层级范围(`all:read`, (中文(简体) ), `all:write`, (中文(简体) ), `all:admin`) (中文(简体) ).
-   带有单独密钥集的简单指示符号 瞄准符和访问符 (单位:千美元)`/.well-known/scoped-jwks.json`键入 `scoped-...`) (中文(简体) ). 年纪大的人只知道 `/.well-known/jwks.json` 并拒绝这些标志, 所以一个范围化的标志 从来没有发挥充分的作用 用于未升级的服务。 拒绝将访问令牌拆分成 cookie, 范围化 符号不能带有超admin的债权,必须过期,只能接受RS256.
-   在范围感知服务中,每个读出会话的路由必须首先检查范围: `requireScope(...)` 编号 : `assertReqScope(req, ...)`,或 `allowAnyScope` 编号 : `markScopeChecked(req)` 如果任何范围是好的(会议机制、公共资源)。 否则会话访问者 (单位:千美元)`session.req()`, (中文(简体) ), `reqSession()` 对范围限定的会话进行回答,也只回答: 原始内容 `user.scope` 索赔存在。 不受限制的会议不涉及.
    -   标出每条路线的瞄准镜,路线需要的射程最窄.
    -   永远不适用 `allowAnyScope` 整个应用程序,会议机制本身之外:将开放 每条前往每个目标的道路.
    -   整个请求的标记会持续: 检查范围与呼叫的路径 `next()` 输入 另外一个操作员将标记传给它.
-   范围化操作可以从浏览器中在其他域上使用:挂载 `session.bearerCors()` 在此之前 了解范围服务的路线。 一通电话 `Authorization: Bearer` 由任意 来源( 来源)`Access-Control-Allow-Origin: *`和飞行前的答案 直接说 无记名符号不是环境,所以来源没有增加任何内容:其范围是什么 限制。 没有无记名信使的电话,没有CORS头条。 中间器件什么也不做,除非 会议是 `scopeAware`,因此执行范围 和打开范围操作到浏览器 一起来.
-   网页`ws-server`拒绝扩大范围的会议,除非服务通过 `start(server, db, canSubscribe, { channelScopes })`数字 : `channelScopes(channel)` 返回范围 或 `undefined` 拒绝在那里进行范围会议(403). `canSubscribe` 之后仍然适用。 范围检查每个订阅消息, 无任何 标记在升级请求上.
-   `session.reqForLogs(req)` 仅读取记录的会话; 绝不使用它来授权. 它从来不扔和忽略范围检查要求; 401/403拒绝是沉默的,其他 错误作为内部错误报告.
-   `session.readState`, (中文(简体) ), `readStateFromCookie` 财务报告和审定财务报表 `readStateFromBearer` 原始读取器: 无路径 瞄准镜,没有请求缓存。 它们不是用于授权的.

## 网页和身份

-   Websocket 服务器 : [`data-fair-ws` 技能](https://github.com/data-fair/lib/tree/main/skills/data-fair-ws)。 。 。 .
-   身份 webhooks( 重命名, GDPR 删除) : [`data-fair-identities` 技能](https://github.com/data-fair/lib/tree/main/skills/data-fair-identities)。 。 。 .
-   `reqIsInternal()` 永远不要给予特权: [`data-fair-security` 技能](https://github.com/data-fair/lib/tree/main/skills/data-fair-security)。 。 。 .

## 常见问题

### @data-fair/lib-express 是什么？

与数据公平堆栈中Express的使用相關的中相器和公用功能\.

### 如何安装 @data-fair/lib-express？

在项目目录运行 npm install @data-fair/lib-express，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：express（5）、@data-fair/lib-node（^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @data-fair/lib-express 支持 TypeScript 吗？

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

### @data-fair/lib-express 支持 ESM 还是 CommonJS？

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

### @data-fair/lib-express 可以商用吗？

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

### @data-fair/lib-express 的下载量有多少？

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

### @data-fair/lib-express 还在维护吗？

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