@xiao-ying/miniapp-request-proxy

轻量中间件，给 @xiao-ying/miniapp-request 动态改写请求 URL，用于接入任意代理服务。采用「builder-first」设计：中间件只负责调用你提供的 buildUrl 函数；不同的 URL 生成策略通过工厂函数提供，互不耦合。

安装

pnpm add @xiao-ying/miniapp-request @xiao-ying/miniapp-request-proxy

快速使用

路径模式（默认推荐）：

import { createXyRequestClient } from '@xiao-ying/miniapp-request'
import {
  createRequestProxyMiddleware,
  createPathUrlBuilder
} from '@xiao-ying/miniapp-request-proxy'

const client = createXyRequestClient({ baseURL: 'https://my-target.com' })
client.use(createRequestProxyMiddleware({
  buildUrl: createPathUrlBuilder({ prefix: 'https://my-proxy.com/request' })
}))

await client.get('/path/to/pages')
// 实际命中 https://my-proxy.com/request/https%3A%2F%2Fmy-target.com%2Fpath%2Fto%2Fpages

查询参数模式：

client.use(createRequestProxyMiddleware({
  buildUrl: createQueryUrlBuilder({
    prefix: 'https://my-proxy.com/entry',
    queryParam: 'target',
    encodeTarget: true
  })
}))
// 结果示例：https://my-proxy.com/entry?target=https%3A%2F%2Fmy-target.com%2Ffoo

自定义模式（完全自定义拼接逻辑）：

import { createRequestProxyMiddleware } from '@xiao-ying/miniapp-request-proxy'

client.use(createRequestProxyMiddleware({
  buildUrl: ({ target }) => `https://my-proxy.com/custom/${btoa(target)}`
}))

内网代理常驻 + DEV 叠加 dev-proxy（链式代理）：

client.use(createRequestProxyMiddleware({
  buildUrl: ({ target }) =>
    `https://inner-proxy.company.com/request/${encodeURIComponent(target)}`
}))

if (import.meta.env.DEV) {
  client.use(createRequestProxyMiddleware({
    buildUrl: ({ target }) =>
      `${import.meta.env.VITE_XY_PROXY_PREFIX || '/dev-proxy/'}${encodeURIComponent(target)}`
  }))
}

API

createRequestProxyMiddleware(options)

• buildUrl (必填)：({ target, kind }) => string，返回最终要请求的 URL。
• skipIf (可选)：函数返回 true 时跳过改写，保持原 URL。
• injectTargetHeader (可选，默认 true)：在改写前把原始目标 URL 写入请求头 xy-proxy-target，便于下游代理识别。

WebSocket 代理

miniapp-request-proxy 也提供 xy.ws 的代理中间件与 URL builder：

import { createXyWsClient } from '@xiao-ying/miniapp-request'
import {
  createWsProxyMiddleware,
  createWsPathUrlBuilder
} from '@xiao-ying/miniapp-request-proxy'

const wsClient = createXyWsClient()
wsClient.use(createWsProxyMiddleware({
  buildUrl: createWsPathUrlBuilder({ prefix: '/dev-proxy/' })
}))

createWsProxyMiddleware(options)

• buildUrl (必填)：({ target }) => string，返回最终要连接的 WS URL。
• skipIf (可选)：函数返回 true 时跳过改写，保持原 URL。

预设 WS URL builder

• createWsPathUrlBuilder({ prefix, encodeTarget = true })
• createWsQueryUrlBuilder({ prefix, queryParam = 'target', encodeTarget = true })
• createWsNoopUrlBuilder()

预设 URL builder

• createPathUrlBuilder({ prefix, encodeTarget = true })
  • prefix 可为完整域名（可带路径）或路径前缀，自动去除尾随斜杠。
  • 内置防重复包装，避免二次代理。
• createQueryUrlBuilder({ prefix, queryParam = 'target', encodeTarget = true })
  • 如果 prefix 自带查询串，会自动用 & 追加参数。
• createNoopUrlBuilder()：原样返回 target，便于调试或按需关闭改写。

行为说明

• 中间件会修改 ctx.request.url，随后继续后续中间件与最终 xy.request/uploadFile/downloadFile。
• 默认会额外注入 xy-proxy-target: <原始URL> 请求头，下游可用、网关前会移除；若不需要可设置 injectTargetHeader: false。
• encodeTarget 默认使用 encodeURIComponent，可关闭以适配特殊网关。
• 代理前缀支持形如 https://proxy.com, https://proxy.com/request, /dev-proxy 等；内部会标准化并去除尾斜杠。
• 已经符合代理格式的 URL 会被识别并跳过，防止重复包装。

许可

Shanghai Plum Technology Ltd. Software License Agreement