# @easyweb/authentication 中文文档 规范地址：https://npmcn.com/package/%40easyweb/authentication/ 版本：2\.2\.0 npm 元数据更新时间：2026-08-27T06:00:29.803Z 中文译文更新时间：2026-11-13T04:19:08.227Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40easyweb/authentication 原文对照：https://npmcn.com/package/%40easyweb/authentication/?lang=original 项目主页：https://github.com/Alpine-Solusi/website-builder#readme 源码仓库：https://github.com/Alpine-Solusi/website-builder ## 关键信息（来自 npm 元数据） - 包体积（解压后）：35.8 kB，30 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=18\.0\.0 - 运行依赖：0 个 - peer 依赖：@easyweb/errors ^1\.0\.0，@easyweb/logging ^1\.0\.0，express ^5\.0\.0，jsonwebtoken ^9\.0\.0 - 首次发布：2026-08-05T16:44:49.468Z - 最新版本发布：2026-08-27T06:00:29.611Z - 近 30 天下载量：3439（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：4（近 12 个月 4 个） ## 中文简介 Easyweb 微服务共享认证原始:无国籍的 JWT 中间软件,请求上下文,以及符号验证帮助器 ## 安装 ```sh npm install @easyweb/authentication ``` 也可以使用：`pnpm add @easyweb/authentication`、`yarn add @easyweb/authentication`、`bun add @easyweb/authentication` ## README # @easyweb/认证 共享Easyweb微服务认证原始——无国籍的JWT中件, 请求文本中间软件,以及符号验证工具服务. 附带到 [`@easyweb/events`](https://www.npmjs.com/package/@easyweb/events) 页:1 通讯,和 [`@easyweb/errors`](https://www.npmjs.com/package/@easyweb/errors) 页:1 hTTP 错误分类. ## 2.1.0. —— `SUPER_ADMIN` 现在满足 `authorize(["ADMIN"])` `authorize()` 是一个精确的字符串匹配。 平台上的每个管理员路线都会被写入 `authorize(["ADMIN"])`认证服务 `admin-seed.ts` 授予拖曳符操作员 `SUPER_ADMIN` 默认 —— 因此种子账户无法调用单个管理路径 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}这个平台. `SUPER_ADMIN` 现在暗示 `ADMIN`没有任何其它意义: `ADMIN` 蓄意 已经 **没有** 隐含 `USER`因为那边缘会无声地拓宽每一个未来的顾客 前往工作人员的路线. **增加,只扩大.** 仍然在2.0.0的服务 表现得和它一样 `SUPER_ADMIN` 仅仅被锁在那里——所以这不需要协调部署。 自兹 每个服务声明 `^2.0.0` 但从一个锁文件安装,用: ```bash npm i @easyweb/authentication@^2.1.0 ``` 新的 `effectiveRoles(roles)` 导出对自己的服务进行同样的扩展 守护(特别是Auth-service的DB后置中件). 现状不变: `authorize()` 还投出 `NotAuthorizedError`,这是 **401 (中文(简体) )** 即使是一个签了名的来电 角色不对 每个服务是http套接字. 需要从"不允许"中告诉"未签入"的来电者必须检查角色本身. ## 升级到 2. 0. 0 — 断裂 错误类已移动到 `@easyweb/errors`。错误处理是交叉的,并且 与JWTs无关;服务需要 `ConflictError` 不必依赖 它的认证包. ```diff - import { NotAuthorizedError } from "@easyweb/authentication"; + import { NotAuthorizedError } from "@easyweb/errors"; ``` `@easyweb/errors` 是一个 **依赖性** - 和这个包一起安装 不要让 它最后被窝在地上 `node_modules/@easyweb/authentication/`: 两份 `CustomError` 表示 `instanceof` 跨越边界失败, 错误处理器会回答 500块,每分每分 每分每分 每分每分每分每分每分每分每分 每分每分每分每分每分 每分每分每分每分每分每分 每分每分每分每分每分每分每分每分每分 每分每分每分每分每分每分每分每分每分每分每分 每分每分每分每分每分每分每分每分每分每分500 校验 `npm ls @easyweb/errors`。 。 。 . 2.0.0中也是新的: `extractToken` 财务报告和审定财务报表 `isValidAccessPayload` 用于服务 保存自己的DB后置中件(见下文),否则将复制. ## 安装 ```bash npm install @easyweb/authentication ``` `express@^5` 财务报告和审定财务报表 `jsonwebtoken@^9` 是同伴的依赖关系——消费服务 提供他们. ## 使用量 包里没有写 `process.env`。在启动时,配置会被绑定,所以 软件包从不到达服务 `config` 模块. ```ts import express from "express"; import cookieParser from "cookie-parser"; import { createAuthMiddleware, requestContext } from "@easyweb/authentication"; import config from "./config"; const app = express(); app.use(cookieParser()); // required: the middleware reads the accessToken cookie app.use(requestContext); const authMiddleware = createAuthMiddleware(config.jwt); // config.jwt must supply { secret, issuer, audience } matching auth-service's app.get("/me", authMiddleware.authenticate, (req, res) => { res.json(req.user); // { id, email, username, roles, permissions } }); app.get("/feed", authMiddleware.optionalAuth, (req, res) => { res.json({ personalised: Boolean(req.user) }); }); app.delete( "/admin/:id", authMiddleware.authenticate, authMiddleware.authorize(["admin"]), handler, ); ``` 嵌入符( 只有自动服务) : ```ts import { createJwtSigner } from "@easyweb/authentication"; const signAccessToken = createJwtSigner(config.jwt); // config.jwt additionally needs accessTokenTtlSeconds ``` ## 它所证实的,和所没有的 `authenticate` 实值 **无国籍人**它检查签名、签发人、受众、过期日期和 有效载荷是一个完善的进入标志。 它没有进行数据库查询. 在认证服务中注销或会话, 此处将隐蔽, 直至访问令牌 期满`JWT_ACCESS_TOKEN_TTL_SECONDS`页:1 如果需要立即提供服务 撤销,它必须保留自己的DB后置中件——认证服务就是这样做的. `req.user.permissions` 总是 `[]`。访问符上没有 `permissions` 索赔; author-service根据请求时间解决自己的表格中的内容。 守护此阵列 将拒绝每一个请求. ## 出口 | 导出 | 目的 | | --- | --- | | `createAuthMiddleware(config)` | `{ authenticate, optionalAuth, authorize }` | | `requestContext` | 传播/生成 `x-request-id` | | `createJwtVerifier(config)` | `(token) => JwtAccessPayload`,丢入无效 | | `createJwtSigner(config)` | `(claims) => string` | | `extractToken(req)` | 熊头头,然后 `accessToken` 饼干 | | `isValidAccessPayload(decoded)` | 类型后卫: 这是很好的形状吗 _访问_ 标志? | | `effectiveRoles(roles)` | 通过影响图(2.1.0)扩展的所起作用 | | `effectiveRoles(roles)` | 通过影响图(2.1.0)扩展的所起作用 | | `JwtAccessPayload`, (中文(简体) ), `JwtAccessClaims`, (中文(简体) ), `JwtVerifyConfig`, (中文(简体) ), `JwtSignConfig` | 类型 | `extractToken` 财务报告和审定财务报表 `isValidAccessPayload` 用于必须保持 DB 支持的服务 中间软件。 他们以前是私人的,所以Auth-service复制了他们—— 和副本 漂来漂去. 如果您需要使用不同错误消息的相同的检查, 请导入这些 而不是重新执行它们. 导入软件包也增加了 `Express.Request` 与 `user`, (中文(简体) ), `auth`,以及 `requestId`。删除任何本地副本 `declare global` 块或类型脚本 报告重复成员. ## 托肯合同 `JwtAccessPayload` 是服务所商定的唯一的形状。 改变它打破每一个 消费者——撞倒了主要版本. ## 许可证 麻省理工学院 ## 常见问题 ### @easyweb/authentication 是什么？ Easyweb 微服务共享认证原始:无国籍的 JWT 中间软件,请求上下文,以及符号验证帮助器 ### 如何安装 @easyweb/authentication？ 在项目目录运行 npm install @easyweb/authentication，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@easyweb/errors（^1\.0\.0）、@easyweb/logging（^1\.0\.0）、express（^5\.0\.0）、jsonwebtoken（^9\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @easyweb/authentication 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @easyweb/authentication 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @easyweb/authentication 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @easyweb/authentication 可以商用吗？ @easyweb/authentication 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @easyweb/authentication 的下载量有多少？ 根据 npm 官方下载统计，@easyweb/authentication 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,439 次，日均约 115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @easyweb/authentication 还在维护吗？ 最新版本 2\.2\.0 发布于 2026/08/27（2 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/08/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。