ElysiaJS 中文网

主题

配置 ​

¥Config

Eden Treaty 接受 2 个参数：

¥Eden Treaty accepts 2 parameters:

  • urlOrInstance - URL 端点或 Elysia 实例

  • 选项（可选） - 自定义获取行为

urlOrInstance ​

接受 URL 端点作为字符串或 Elysia 实例的字面值。

¥Accept either URL endpoint as string or a literal Elysia instance.

Eden 将根据类型更改行为，如下所示：

¥Eden will change the behavior based on type as follows:

URL 端点（字符串） ​

¥URL Endpoint (string)

如果传递了 URL 端点，Eden Treaty 将使用 fetch 或 config.fetcher 创建向 Elysia 实例的网络请求。

¥If URL endpoint is passed, Eden Treaty will use fetch or config.fetcher to create a network request to an Elysia instance.

typescript
import { treaty } from '@elysiajs/eden'
import type { App } from './server'

const api = treaty<App>('localhost:3000')

你可以为 URL 端点指定或不指定协议。

¥You may or may not specify a protocol for URL endpoint.

Elysia 将自动附加端点，如下所示：

¥Elysia will append the endpoints automatically as follows:

  1. 如果指定了协议，请直接使用 URL。
  2. 如果 URL 是 localhost 且环境变量不是 production，请使用 http
  3. 否则使用 https

This also applies to Web Socket as well for determining between ws:// or wss://.

Elysia 实例 ​

¥Elysia Instance

如果传递了 Elysia 实例，Eden Treaty 将创建一个 Request 类并直接传递给 Elysia.handle，而无需创建网络请求。

¥If Elysia instance is passed, Eden Treaty will create a Request class and pass to Elysia.handle directly without creating a network request.

这使我们能够直接与 Elysia 服务器交互，而无需请求开销或启动服务器。

¥This allows us to interact with Elysia server directly without request overhead, or the need to start a server.

typescript
import { Elysia } from 'elysia'
import { treaty } from '@elysiajs/eden'

const app = new Elysia()
    .get('/hi', 'Hi Elysia')
    .listen(3000)

const api = treaty(app)

如果传递的是实例，则无需传递泛型，因为 Eden Treaty 可以直接从参数推断类型。

¥If an instance is passed, generic is not needed to be passed as Eden Treaty can infer the type from a parameter directly.

建议使用此模式执行单元测试，或创建类型安全的反向代理服务器或微服务。

¥This pattern is recommended for performing unit tests, or creating a type-safe reverse proxy server or micro-services.

选项 ​

¥Options

Eden Treaty 的第二个可选参数用于自定义获取行为，接受以下参数：

¥2nd optional parameter for Eden Treaty to customize fetch behavior, accepting parameters as follows:

  • fetch - 添加默认参数以进行获取初始化 (RequestInit)

  • headers - 定义默认标头

  • fetcher - 自定义获取函数，例如 Axios，unfetch

  • onRequest - 在触发前拦截并修改获取请求

  • onResponse - 拦截并修改获取的响应

获取 ​

¥Fetch

默认参数附加到 fetch 的第二个参数，扩展了 Fetch.RequestInit 的类型。

¥Default parameters append to 2nd parameters of fetch extends type of Fetch.RequestInit.

typescript
export type App = typeof app 
import { treaty } from '@elysiajs/eden'
// ---cut---
treaty<App>('localhost:3000', {
    fetch: {
        credentials: 'include'
    }
})

所有传递给 fetch 的参数都会传递给 fetcher，这相当于：

¥All parameters that are passed to fetch will be passed to fetcher, which is equivalent to:

typescript
fetch('http://localhost:3000', {
    credentials: 'include'
})

标题 ​

¥Headers

提供额外的默认获取标头，即 options.fetch.headers 的简写。

¥Provide an additional default headers to fetch, a shorthand of options.fetch.headers.

typescript
treaty<App>('localhost:3000', {
    headers: {
        'X-Custom': 'Griseo'
    }
})

所有传递给 fetch 的参数都会传递给 fetcher，这相当于：

¥All parameters that passed to fetch, will be passed to fetcher, which is an equivalent to:

typescript
fetch
('localhost:3000', {
    
headers
: {
        'X-Custom': 'Griseo'
    }
})

headers 可以接受以下参数：

¥headers may accept the following as parameters:

  • 对象

  • 函数

标题对象 ​

¥Headers Object

如果传递了对象，则会直接传递给 fetch。

¥If object is passed, then it will be passed to fetch directly

typescript
treaty<App>('localhost:3000', {
    headers: {
        'X-Custom': 'Griseo'
    }
})

函数 ​

¥Function

你可以将 headers 指定为函数，以根据条件返回自定义 headers。

¥You may specify headers as a function to return custom headers based on condition

typescript
treaty<App>('localhost:3000', {
    headers(path, options) {
        if(path.startsWith('user'))
            return {
                authorization: 'Bearer 12345'
            }
    }
})

你可以返回对象并将其值附加到获取标头中。

¥You may return object to append its value to fetch headers.

headers 函数接受 2 个参数：

¥headers function accepts 2 parameters:

  • string 路径 - 将发送给参数的路径

    • 注意：主机名将被排除，例如： (/user/griseo)

  • RequestInit 选项：通过 fetch 的第二个参数传递的参数

数组 ​

¥Array

如果需要多个条件，你可以将 headers 函数定义为数组。

¥You may define a headers function as an array if multiple conditions are needed.

typescript
treaty<App>('localhost:3000', {
    headers: [
      (path, options) => {
        if(path.startsWith('user'))
            return {
                authorization: 'Bearer 12345'
            }
        }
    ]
})

即使值已返回，Eden Treaty 也会运行所有函数。

¥Eden Treaty will run all functions even if the value is already returned.

标题优先级 ​

¥Headers Priority

如果出现重复，Eden Treaty 将按以下方式优先处理请求头：

¥Eden Treaty will prioritize the order headers if duplicated as follows:

  1. 内联方法 - 直接传入方法函数
  2. headers - 传入 config.headers
  • 如果 config.headers 是数组，则优先处理后面的参数。
  1. fetch - 传入 config.fetch.headers

例如，对于以下示例：

¥For example, for the following example:

typescript
const api = treaty<App>('localhost:3000', {
    headers: {
        authorization: 'Bearer Aponia'
    }
})

api.profile.get({
    headers: {
        authorization: 'Bearer Griseo'
    }
})

这将导致：

¥This will result in:

typescript
fetch('http://localhost:3000', {
    headers: {
        authorization: 'Bearer Griseo'
    }
})

如果内联函数未指定标头，则结果将改为 "承载 Aponia"。

¥If inline function doesn't specified headers, then the result will be "Bearer Aponia" instead.

获取器 ​

¥Fetcher

提供自定义获取函数，而不是使用环境的默认获取函数。

¥Provide a custom fetcher function instead of using an environment's default fetch.

typescript
treaty<App>('localhost:3000', {
    fetcher(url, options) {
        return fetch(url, options)
    }
})

如果你想使用 fetch 以外的其他客户端（例如 Axios 的 unfetch），建议替换 fetch。

¥It's recommended to replace fetch if you want to use other client other than fetch, eg. Axios, unfetch.

OnRequest ​

在触发前拦截并修改获取请求。

¥Intercept and modify fetch request before firing.

你可以返回对象并将其值附加到 RequestInit 中。

¥You may return object to append the value to RequestInit.

typescript
treaty<App>('localhost:3000', {
    onRequest(path, options) {
        if(path.startsWith('user'))
            return {
                headers: {
                    authorization: 'Bearer 12345'
                }
            }
    }
})

如果返回值，Eden Treaty 将对返回值和 value.headers 进行浅合并。

¥If value is returned, Eden Treaty will perform a shallow merge for returned value and value.headers.

onRequest 接受 2 个参数：

¥onRequest accepts 2 parameters:

  • string 路径 - 将发送给参数的路径

    • 注意：主机名将被排除，例如： (/user/griseo)

  • RequestInit 选项：通过 fetch 的第二个参数传递的参数

数组 ​

¥Array

如果需要多个条件，你可以将 onRequest 函数定义为数组。

¥You may define an onRequest function as an array if multiples conditions are need.

typescript
treaty<App>('localhost:3000', {
    onRequest: [
      (path, options) => {
        if(path.startsWith('user'))
            return {
                headers: {
                    authorization: 'Bearer 12345'
                }
            }
        }
    ]
})

即使值已返回，Eden Treaty 也会运行所有函数。

¥Eden Treaty will run all functions even if the value is already returned.

onResponse ​

拦截并修改获取的响应或返回新值。

¥Intercept and modify fetch's response or return a new value.

typescript
treaty<App>('localhost:3000', {
    onResponse(response) {
        if(response.ok)
            return response.json()
    }
})

onRequest 接受 1 个参数：

¥onRequest accepts 1 parameter:

  • 响应 Response - Web 标准响应通常从 fetch 返回

数组 ​

¥Array

如果需要多个条件，你可以将 onResponse 函数定义为数组。

¥You may define an onResponse function as an array if multiple conditions are need.

typescript
treaty<App>('localhost:3000', {
    onResponse: [
        (response) => {
            if(response.ok)
                return response.json()
        }
    ]
})

与 headers 和 onRequest 不同，Eden Treaty 会循环遍历函数，直到找到返回值或抛出错误，返回值将用作新的响应。

¥Unlike headers and onRequest, Eden Treaty will loop through functions until a returned value is found or error thrown, the returned value will be use as a new response.