# @aglyn/shared-util-http 中文文档

规范地址：https://npmcn.com/package/%40aglyn/shared-util-http/

版本：1\.18\.0
npm 元数据更新时间：2026-11-07T06:43:59.209Z
中文译文更新时间：2026-11-05T21:30:19.908Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aglyn/shared-util-http
原文对照：https://npmcn.com/package/%40aglyn/shared-util-http/?lang=original
项目主页：https://aglyn.com/
源码仓库：https://github.com/aglyn/aglyn

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

- 包体积（解压后）：146 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：next ^16\.3\.3
- 首次发布：2026-09-20T23:54:41.945Z
- 最新版本发布：2026-11-07T06:43:58.893Z
- 近 30 天下载量：17625（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：152（近 12 个月 152 个）

## 中文简介

获取 API 和 Next.js 请求处理器的小型 HTTP 帮助器: CORS 、 请求头、 ID- token cookie、 同源重定向检查、 URL 方案允许列表和认证 `fetch`它主要是Aglyn大包(QQAglyn/agl)的附属物

## 安装

```sh
npm install @aglyn/shared-util-http
```

也可以使用：`pnpm add @aglyn/shared-util-http`、`yarn add @aglyn/shared-util-http`、`bun add @aglyn/shared-util-http`

## README

# @aglyn/ shared- util- http

获取 API 和 Next.js 请求处理器的小型 HTTP 帮助器: CORS 、 请求头、 ID- token cookie、 同源重定向检查、 URL 方案允许列表和认证 `fetch`它主要是Aglyn大型包件的附属物(Aglyn包件)`@aglyn/aglyn`,插件,租户运行时间),可以自行使用.

> 从Aglyn monorepo出版到npm. 随后的版本 [语义版本](https://semver.org/)。 。 。 .

## 安装

```
npm install @aglyn/shared-util-http
```

同伴依赖 : `next` (单位:千美元)`16.3.3`),可选. 使用取 Next.js 对象的助手(`NextRequest`, (中文(简体) ), `NextResponse`, (中文(简体) ), `NextApiRequest`比如饼干帮手 下面的子路径模块只使用网络标准.

## 里面有什么东西

从软件包根 :

-   科斯特尔: `corsHandleResponse(req, res, options?)` 财务报告和审定财务报表 `corsBuildResponseHandler(options?)`,可重复使用的配置。 逐项拒绝:没有 `origin` 选项. `credentials` 从不与 `*` 源代码。 飞行前 `OPTIONS` 除非 `preflightContinue` 已经设定。 下层部件 : `getOriginHeaders`, (中文(简体) ), `getOriginHeadersFromRequest`, (中文(简体) ), `getAllowedHeaders`, (中文(简体) ), `isOriginAllowed`。 。 。 .
-   `getRequestHeader(request, name)` - 阅读一个标题 从任何一个获取 `Request` 或一个 `NextApiRequest`。 。 。 .
-   `getAbsoluteUrl(path, request?)` - 从 `host` 页眉( 服务器) 或 `window.location` (浏览器).
-   `cookieGetUserIdToken(request)` 编号 : `cookieSetUserIdToken(request, response, token, options?)` - 读和写用户 ID -token cookie, `httpOnly` 默认.
-   类型 : `CorsOptions`, (中文(简体) ), `StaticOrigin`, (中文(简体) ), `OriginFn`。 。 。 .

仅通过子路径(不从根再出):

-   `@aglyn/shared-util-http/safe-redirect` - 说吧 `isSameOriginPath(candidate)` 财务报告和审定财务报表 `safeSameOriginPath(candidate, fallback = '/')`。它们不匹配字符串的图案,而是用URL解析器与探针源进行解析,只有在源头不变的情况下才接受,源头捕获 `//host`, (中文(简体) ), `/\host`,以及标签或新线的花招.
-   `@aglyn/shared-util-http/safe-url-scheme` - 说吧 `hasSafeLinkScheme(value)` (单位:千美元)`http`, (中文(简体) ), `https`, (中文(简体) ), `mailto`, (中文(简体) ), `tel`, (中文(简体) ), `sms`,或没有计划)和 `hasSafeMediaScheme(value)` (单位:千美元)`http`, (中文(简体) ), `https`,或者没有计划。 他们只检查方案;之后你仍须从值中逃入属性中.
-   `@aglyn/shared-util-http/bounded-await` - 说吧 `boundedAwait(work, ms, fallback, label)` 财务报告和审定财务报表 `createSettledValueCache()`。第一个答案是 `work`'结果,或与 `fallback` 一次 `ms` 已经通过,使用实时计时器,而不是信任中止信号; `work` 可能是一个函数 `AbortSignal` 在截止日期终止。 获胜的最后期限写一个结构化 `console.warn` 每个标签一分钟。 第二个是 TTL 缓存,它持有已结算的值并拒绝承诺,有一个 `readThrough(key, load, ttlFor)` 只能储存一次 `load` 已经解决.
-   `@aglyn/shared-util-http/authorized-token` - 说吧 `resolveIdToken(user, options?)`, (中文(简体) ), `authorizedFetch(user, input, init?, options?)`, (中文(简体) ), `describeCallFailure(error, fallback)`, (中文(简体) ), `AuthorizationUnavailableError`, (中文(简体) ), `ID_TOKEN_TIMEOUT_MS`。 。 。 . `user` 任何与一个 `getIdToken()` 方法。 等待的标志有期限, 当没有标志的时候 `authorizedFetch` 什么都不给,我下定决心 `401`\- 有原因的形状反应.

## 使用量

```ts
import { corsBuildResponseHandler } from '@aglyn/shared-util-http'
import { safeSameOriginPath } from '@aglyn/shared-util-http/safe-redirect'

const cors = corsBuildResponseHandler({
  origin: ['https://app.example.com'],
  credentials: true,
})

export async function GET(req: Request) {
  return cors(req, Response.json({ ok: true }))
}

// Anything that would leave the origin becomes '/'.
const next = safeSameOriginPath(new URL(location.href).searchParams.get('next'))
```

## 怎样才合适

A 类 `shared` 软件包:通用,对Aglyn的模型一无所知。 共享软件包只能导入其他共享软件包; 此软件包取决于 `@aglyn/shared-data-enums` (HTTP状态代码和饼干键). `@aglyn/shared-util-next`, (中文(简体) ), `@aglyn/shared-util-rest-api`, (中文(简体) ), `@aglyn/shared-util-email`, (中文(简体) ), `@aglyn/aglyn`,租户运行时间包和大多数插件都依赖于它.

## 许可证

阿帕奇2.0 (英语). 资料来源: [https://github.com/aglyn/aglyn/tree/main/libs/shared/util/http. 中国植物物种信息数据库](https://github.com/aglyn/aglyn/tree/main/libs/shared/util/http)

## 常见问题

### @aglyn/shared-util-http 是什么？

获取 API 和 Next\.js 请求处理器的小型 HTTP 帮助器: CORS 、 请求头、 ID- token cookie、 同源重定向检查、 URL 方案允许列表和认证 fetch它主要是Aglyn大包\(QQAglyn/agl\)的附属物

### 如何安装 @aglyn/shared-util-http？

在项目目录运行 npm install @aglyn/shared-util-http，或使用 pnpm add / yarn add / bun add。

### @aglyn/shared-util-http 支持 TypeScript 吗？

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

### @aglyn/shared-util-http 支持 ESM 还是 CommonJS？

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

### @aglyn/shared-util-http 可以商用吗？

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

### @aglyn/shared-util-http 的下载量有多少？

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

### @aglyn/shared-util-http 还在维护吗？

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