@snail-js/api 0.1.27 → 1.0.0

package/README.md

@@ -1,678 +1,198 @@
-<p>
-  <img src="https://img.shields.io/badge/TypeScript-1e80ff"></img>
-  <img src="https://img.shields.io/npm/v/axios?label=axios&labelColor=1e80ff&color=67C23A"></img>
-  <img src="https://img.shields.io/npm/v/reflect-metadata?label=reflect-metadata&labelColor=1e80ff&color=67C23A"></img>
-</p>
+# @snail-js/api
 
-中文文档|<a href='https://github.com/limingchang/snail/blob/master/packages/api/README_EN.md'>English Document</a>
+> 装饰器驱动、一切皆插件的 TypeScript 请求管理库，仅基于 [axios](https://axios-http.com/)。
 
-## 项目介绍
+[![TypeScript](https://img.shields.io/badge/TypeScript-7.0-1e80ff)](https://www.typescriptlang.org/)
+[![axios](https://img.shields.io/badge/axios-1.20-67C23A)](https://axios-http.com/)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-- 基于 Axios 二次封装
-- 使用`reflect-metadata`创建和处理元数据
-- 提供装饰器定义请求请求的方式，支持所有请求方法和 SSE
+- **装饰器驱动** — `@Server` / `@Api` / `@Get` 定义请求，设计思想来自 Nest.js
+- **一切皆插件** — 缓存、拦截器、请求池、版本、校验、转换、框架适配全部是插件，核心只做三件事
+- **零运行时依赖** — `dependencies` 是空的；axios 是 peer 依赖，也不需要 `reflect-metadata`
+- **完整的类型推断** — 从方法声明的返回类型推断 `data` 类型，无需手写泛型
+- **请求策略** — alova 风格的 `useRequest` / `usePagination` / `useRetriableRequest` / `useDownload` 等 hook
+- **浏览器与服务端皆可** — 核心只用平台能力，没有 DOM 依赖；SSR 与 Node 服务同样适用
 
 ## 安装
 
-`npm install @snail-js/api`
+```bash
+pnpm add @snail-js/api axios
+```
+
+`vue`、`react`、`zod` 都是**可选**的 peer 依赖，只有用到对应插件/策略时才需要安装。
 
-## 使用
+## 快速开始
 
-1. 请开启`TypeScript`相关装饰器配置
+### 1. 配置 TypeScript
 
 ```json
-// tsconfig.json
 {
-  "module": "ESNext",
-  // 模块解析策略
-  "moduleResolution": "node",
-  "baseUrl": ".",
-  // target 必须大于ES6
-  "target": "ESNext",
-  // lib 需要包含大于ES6的ES版本
-  "lib": ["ESNext", "DOM"],
-  // 包含reflect-metadata类型
-  "types": ["reflect-metadata"],
-  "emitDecoratorMetadata": true,
-  "experimentalDecorators": true,
-
-  "skipLibCheck": true,
-  "strictNullChecks": false
+  "compilerOptions": {
+    "experimentalDecorators": true
+  }
 }
 ```
 
-2. 创建`Snail`后端基本配置实例
+> **不需要** `reflect-metadata`，也**不需要** `emitDecoratorMetadata`。
+> TypeScript 7 已不再产出 `design:*` 元数据，本库使用自己的元数据存储。
+> 如果你从旧版本迁移，请参照[迁移指南](https://snail-js.github.io/api/guide/migration)。
+
+### 2. 定义服务
 
-```typescript
+```ts
 // service.ts
-import { SnailServer, Server } from "@snail-js/api";
+import { Server, SnailServer } from "@snail-js/api";
 
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
+@Server({ baseURL: "/api", timeout: 5000 })
 class BackEnd extends SnailServer {}
 
-export const Service = new BackEnd();
-```
-
-3. 创建 Api 实例
-
-```typescript
-// user.ts
-import { Api, Get, Post, Query, Data, SnailApi } from "@snail-js/api";
-
-import { Service } from "./service";
-
-@Api("user")
-class UserApi extends SnailApi {
-  @Get()
-  get(@Query("id") id: string) {}
-
-  @Post()
-  create(@Data() user: User) {}
-}
-// 创建并导出api
-export const userApi = Service.createApi(UserApi);
-```
-
-3. 发送请求
-
-```typescript
-import { userApi } from "./user";
-
-const { send:getUser, onSuccess, onError, onHitCache } = await userApi.get();
-
-const data = await getUser("1");
+export const service = new BackEnd();
 ```
 
-## `SnailMethod` 实例
-
-- 调用`Service.createApi(ApiInstance)`后会为`ApiInstance`内被`RequestMethod`(如：@Get、@Post...)装饰的方法创建一个代理，返回一个函数，此函数包含请求参数，调用此函数返回`SnailMethod` 实例
-
-### `SnailMethod` 实例方法
-
-- `send` 发送请求
-  _异步函数，发送当前请求_
-- `onSuccess` 请求成功回调
-  _注册请求成功事件_
-- `onError` 请求失败回调
-  _注册请求失败事件_
-- `onHitCache` 请求命中缓存回调
-  _注册请求命中缓存事件_
-- `onFinish` 请求完成回调
-  _注册请求完成事件_
-- `registerStrategies` 注册策略
-  _注册方法级策略_
-
-
-### `SnailMethod` 实例属性
-
-- response : AxiosResponse
-- request : AxiosRequestConfig ,最终请求的 request,这个 request 是被 Versioning 和 Strategy 处理过的
-- version : string,最终请求的版本，如果没有开启 Versioning 则为 undefine
-- name : string,完整的 SnailMethod 名称，格式为`ServerName.ApiName.MethodName`
-- error : Error | null,请求失败的错误信息,无错误为 null
-
-### Server 配置
-
-<table>
-  <tr>
-    <th>配置项</th>
-    <th>类型</th>
-    <th>是否必须</th>
-    <th>默认值</th>
-    <th>说明</th>
-  </tr>
-  <tr>
-    <td>name</td>
-    <td>string</td>
-    <td>否</td>
-    <td>默认使用继承`SnailServer`的类名作为name</td>
-    <td>server实例唯一标识，请勿与其他server重复</td>
-  </tr>
-  <tr>
-    <td>baseUrl</td>
-    <td>string</td>
-    <td>否</td>
-    <td>'\'</td>
-    <td>请求后端的api地址前缀，同`axios`的baseUrl</td>
-  </tr>
-  <tr>
-    <td>Versioning</td>
-    <td><a href="#versioningoption">VersioningOption</a></td>
-    <td>否</td>
-    <td>undefine</td>
-    <td>版本管理器配置，默认不开启</td>
-  </tr>
-  <tr>
-    <td>timeout</td>
-    <td>number</td>
-    <td>否</td>
-    <td>5000</td>
-    <td>单位:毫秒；全局超时时间，会被 Api 的 timeout 值覆盖</td>
-  </tr>
-  <tr>
-    <td>cacheManage</td>
-    <td>{type:CacheType,ttl:number}</td>
-    <td>否</td>
-    <td>{
-      type: CacheType.Memory,
-      ttl: 500
-    }</td>
-    <td>缓存管理器,ttl单位为秒</td>
-  </tr>
-  <tr>
-    <td>cacheFor</td>
-    <td>RequestMethod | RequestMethod[] | 'All' | 'all' </td>
-    <td>否</td>
-    <td>Get</td>
-    <td>要启用缓存的方法，默认仅开启Get缓存</td>
-  </tr>
-  <tr>
-    <td>serverStatusCodeRule</td>
-    <td><a href="#SnailServerStatusCodeRuleOptions">SnailServerStatusCodeRuleOptions</a></td>
-    <td>否</td>
-    <td>undefined</td>
-    <td>服务端状态码规则，若配置此项，rule函数返回false时会触发错误</td>
-  </tr>
-  <tr>
-    <td>enableLog</td>
-    <td>boolean</td>
-    <td>否</td>
-    <td>false</td>
-    <td>是否开启日志，用于调试</td>
-  </tr>
-</table>
-
-### Api 配置
-
-- 请使用`@Api()`装饰自定义 Api 类并继承`SnailApi`
-
-<table>
-  <tr>
-    <th>配置项</th>
-    <th>类型</th>
-    <th>是否必须</th>
-    <th>默认值</th>
-    <th>说明</th>
-  </tr>
-  <tr>
-    <td>name</td>
-    <td>string</td>
-    <td>否</td>
-    <td>默认使用继承`SnailApi`的类名作为name</td>
-    <td>api实例唯一标识，请勿与其他api重复</td>
-  </tr>
-  <tr>
-    <td>timeout</td>
-    <td>number</td>
-    <td>否</td>
-    <td></td>
-    <td>请求超时时间;会覆盖Server的timeout设置</td>
-  </tr>
-  <tr>
-    <td>version</td>
-    <td>string</td>
-    <td>否</td>
-    <td></td>
-    <td>api版本号，会覆盖server的`defaultVersion`配置</td>
-  </tr>
-</table>
-
-## 请求方法装饰器
-
-- 在`Api`类中使用，用于标记请求方法
-- 提供 axios 的全部请求方法`Get,Post,Head,Put,Delete,Patch,Options`
-- 参数: `path?: string`; 请求端点路径，与`baseUrl,api.url`共同拼接组成最终请求路径
-
-## 参数装饰器
-
-### 查询参数 `@Query`
-
-- `@Query(key?:string)`
-
-- 单个参数使用
-
-```typescript
-@Api("user")
-class UserApi {
-  @Get()
-  get(@Query("id") id: string, @Query("sign") sign: string) {}
-}
-```
-
-> 传入 key，标记单个查询参数，拼接到请求`?k1=v1&k2=v2`
-
-### 路由参数 `@Params`
-
-- `@Params(key?:string)`
-
-- 单个参数使用
-
-```typescript
-@Api("user/:id/:sign")
-class UserApi {
-  @Get()
-  get(@Params("id") id: string, @Params("sign") sign: string) {}
-}
-```
-
-> 传入 key，标记单个查询参数，拼接到请求`?k1=v1&k2=v2`
+### 3. 定义 API
 
-- 对象参数使用
+```ts
+// user.api.ts
+import { Api, Data, Get, Params, Post, Query } from "@snail-js/api";
+import { service } from "./service";
 
-```typescript
-class RouteParams {
-  id: string;
-  sign: string;
-}
-
-@Api("user/:id/:sign")
-class UserApi {
-  @Get()
-  get(@Params() params: RouteParams) {}
-}
-```
-
-> 不传入 key，会被标记为对象类型查询参数；也能自动拼接到请求
-
-- 混合使用
-
-```typescript
-class RouteParams {
-  id: string;
-  sign: string;
+export interface User {
+  id: number;
+  name: string;
 }
 
-@Api("user/:id/:sign")
+@Api("/user")
 class UserApi {
-  @Get()
-  get(@Params() params: Query, @Params("a") a: number) {}
-}
-```
-
-### 请求数据
-
-- `@Data(key?:string)`
-- 使用方式和`@Params`相同，也支持混合使用
-
-## 策略装饰器`@UseStrategy`
-
-- `@UseStrategy(...Strategy[])`
-
-### 请求策略
-
-- 在请求发送前执行，后面的策略返回结果会覆盖前面的策略
-- 若返回处理后的 request，则使用处理后的 request 发送请求，否则使用原始 request 或上一个策略返回的 request 发送请求
-
-```typescript
-class CustomStrategy extends Strategy {
-  applyRequest(request: AxiosRequestConfig) {
-    request.headers["Access-Token"] = "abcde";
-    return request;
+  /** 方法体永远不会执行，它只用来声明参数类型和返回类型 */
+  @Get("/:id")
+  getUser(@Params("id") id: string, @Query("withProfile") withProfile?: boolean): Promise<User> {
+    return null!;
   }
-}
 
-// 用在Snail，全局的请求策略
-
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-@UseStrategy(CustomStrategy)
-class BackEnd extends Snail<ShanheResponse> {}
-export const Service = new BackEnd();
-// 创建Service实例后再注册策略
-Service.registerStrategies(CustomStrategy);
-
-// 用在Api, 当Api下的方法请求时生效
-@Api("test")
-@UseStrategy(CustomStrategy)
-class Test {}
-const TestApi = Service.createApi(Test);
-// 创建Api实例后再注册策略
-TestApi.registerStrategies(CustomStrategy);
-
-// 用在方法，此方法请求时生效
-@Api("test")
-@UseStrategy(CustomStrategy)
-class Test {
-  @Get()
-  @UseStrategy(CustomStrategy)
-  get() {}
-}
-// 发送请求前注册策略
-const TestApi = Service.createApi(Test);
-const getSomething = TestApi.get();
-{ send, registerStrategies } = getSomething;
-getSomething.registerStrategies(CustomStrategy);
-
-
-```
-
-### 响应策略
-
-- 在收到服务器响应后执行
-- 若返回处理后的 response，则使用处理后的 response 进行下一个策略或返回，否则使用原始 response 或上一个策略返回的 response 返回
-
-```typescript
-// 如何定义
-class CustomStrategy extends Strategy {
-  applyResponse(response: AxiosResponse) {
-    const { status } = response;
-    if (status == 200) {
-      // do something
-    }
-    return response;
+  @Post("/")
+  createUser(@Data() payload: Omit<User, "id">): Promise<User> {
+    return null!;
   }
 }
-```
 
-## 版本管理装饰器`@Versioning`和`@Version`
-
-### 版本管理器`@Versioning(VersioningOption)`
-
-- 全局管理版本
-
-```typescript
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-@Versioning({
-  type: VersioningType.Header,
-  defaultVersion: "0.1.0",
-})
-class BackEnd extends Snail<ShanheResponse> {}
-
-export const Service = new BackEnd();
+export const userApi = service.createApi(UserApi);
 ```
 
-#### <a id="versioningoption">`VersioningOption`</a>类型
+### 4. 发起请求
 
-```typescript
-export enum VersioningType {
-  Uri,
-  Header,
-  Query,
-  Custom,
-}
-
-interface VersioningCommonOption {
-  defaultVersion: string;
-}
+```ts
+// 调用被装饰的方法不会发送请求，它只创建一个待发送的请求对象
+const method = userApi.getUser("1");
+const { data, code, message, fromCache } = await method.send();
 
-export interface VersioningUriOption extends VersioningCommonOption {
-  type: VersioningType.Uri;
-  prefix?: string;
-}
-
-export interface VersioningHeaderOption extends VersioningCommonOption {
-  type: VersioningType.Header;
-  header?: string;
-}
-
-export interface VersioningQueryOption extends VersioningCommonOption {
-  type: VersioningType.Query;
-  key?: string;
-}
-
-export interface VersioningCustomOption extends VersioningCommonOption {
-  type: VersioningType.Custom;
-  extractor: (requestOptions: unknown) => {
-    url: string;
-    headers: Record<string, any>;
-  };
-}
-
-export type VersioningOption =
-  | VersioningUriOption
-  | VersioningHeaderOption
-  | VersioningQueryOption
-  | VersioningCustomOption;
+// data 已经被推断为 User —— 无需手写泛型，也不会有 any
+console.log(data.name);
 ```
 
-### <a id="SnailServerStatusCodeRuleOptions">SnailServerStatusCodeRuleOptions</a> 类型
+单个方法实例可以重复使用，参数可以在 `send()` 时覆盖：
 
-```typescript
-export class SnailServerStatusCodeRuleOptions {
-  // 通常服务端会返回一个状态码，当状态码不符合预期时，会抛出错误
-  // 可以使用此选项来定义服务端状态码的规则
-  // 当rule函数返回false时，会触发错误
-  rule: (statusCode: number) => boolean;
-  // response.data中服务端状态码的key，默认为code
-  key?: string;
-}
-```
-
-### 临时版本修改器`@Version`
-
-- 临时改变方法请求的版本
-
-```typescript
-@Api("test")
-class Test {
-  @Get("HelloWorld")
-  @Version("0.2.0")
-  test() {}
-}
+```ts
+const method = userApi.getUser();
+await method.send("1");
+await method.send("2");
 ```
 
-> 临时改变 api 版本，便于测试
-
-### 缓存装饰器`@HitSource`
-
-- `@HitSource(name:string)`
-- 为被装饰的方法设置缓存失效源，当设置的名称方法被调用且正常响应时，被装饰的方法缓存失效
-- name 格式为：`serverName:apiName:methodName`
-  > 注意：若您配置了 SnailServer/SnailApi 的 name 选项，请使用此 name 作为名称，否则使用类名作为名称
+## 返回结构
 
-```typescript
-@Api("test", { name: "api1" })
-@HitSource("api1")
-class Test {
-  @Get("HelloWorld")
-  @HitSource("api1.test2")
-  test1() {}
+后端返回的数据默认遵循下面的结构：
 
-  @Post()
-  test2() {}
-
-  @Get()
-  // Test类下任何请求成功，这个方法的缓存都会失效
-  @HitSource("api1")
-  test3() {}
-}
+```json
+{ "code": 0, "message": "ok", "data": {} }
 ```
 
-> 当请求`[Post]test`成功时，`[Get]test/HelloWorld`的缓存失效
-> 默认仅 Get 方法会进行缓存 ing 缓存，若要开启其他方法的缓存，请使用`@Server({cacheFor:'all'})`配置
-
-> `test3`方法请求成功时，不缓存
-
-> 注意：要使用缓存，请配置`@Server({CacheManage})`缓存管理器
-
-### 上传进度装饰器`@UploadProgress`
-
-- `@UploadProgress((progressEvent: AxiosProgressEvent) => void)`
-
-### 下载进度装饰器`@DownloadProgress`
-
-- `@DownloadProgress((progressEvent: AxiosProgressEvent) => void)`
-
-## Server Send Event 服务端推送
-
-### 创建 sse 端点
-
-```typescript
-@Sse("sse")
-class ServerSend extend SnailSse {
-
-  @OnSseOpen()
-  handleOpen(event: Event) {
-    console.log("sse-open:", event);
-  }
-
-  @OnSseError()
-  handleError(event: Event) {
-    console.log("sse-error:", event);
-  }
-
-  // 处理默认message事件
-  @SseEvent()
-  handleEvent(event: MessageEvent) {
-    console.log("sse-event[message]:", event.data);
-  }
+三个字段名都可以通过 `@Server({ codeKey, messageKey, dataKey })` 修改；
+结构本身可以通过 `declare module` 重定义：
 
-  // 处理自定义名称事件
-  @SseEvent("chunk")
-  handleEvent(event: Event) {
-    console.log("sse-event[chunk]:", event);
+```ts
+declare module "@snail-js/api" {
+  interface SnailEnvelopeSchema {
+    status: number;
+    msg: string;
+    result: unknown;
   }
 }
-
-export const Sse = Service.createSse(ServerSend);
 ```
 
-### 服务端推送装饰器`@Sse`
-
-- `@Sse(path:string,options?:{withCredentials?: boolean,version?: string;})`
-- 创建一个服务端推送连接，返回一个函数，用于打开 sse 连接
-  - 返回的打开函数调用后会返回`{eventSource:EventSource,close:function}`
-    - eventSource: sse 连接实例
-    - close: 关闭此 sse 连接的方法
-
-### 注册`onopen`装饰器`@OnSseOpen`
-
-- 当`@Sse`装饰的方法被调用时，将`@OnSseOpen`装饰的方法注册为`@Sse`装饰的方法返回的`EventSource`实例`onopen`处理函数
-
-### 注册`onerror`装饰器`@OnSseError`
+`send()` 返回一个 `SnailResult`，而不是裸的信封：
 
-- 当`@Sse`装饰的方法被调用时，将`@OnSseError`装饰的方法注册为`@Sse`装饰的方法返回的`EventSource`实例`onerror`处理函数
+| 字段 | 说明 |
+| --- | --- |
+| `data` | **已解包**的业务数据，绝大多数情况下你只需要它 |
+| `envelope` | 完整信封 `{ code, message, data }` |
+| `response` | 原始 axios 响应 |
+| `code` / `message` | 业务状态码与消息 |
+| `fromCache` | 是否来自缓存 |
+| `config` | 最终生效的请求配置 |
 
-### 事件处理装饰器`@SseEvent`
+## 插件
 
-- `@SseEvent(eventName?:string)`
-- 未传入`eventName`，默认注册为`message`事件处理器
-- 传入`eventName`，注册为对应名称的事件处理器
+插件从子路径按需引入，未使用的插件会被打包器完全剔除：
 
----
+```ts
+import { Cache, Interceptor, RequestPool, Versioning } from "@snail-js/api/plugins";
 
-## TypeScript 支持
-
-### 默认返回类型
-
-```typescript
-export type StandardResponseData<
-  T extends ResponseJsonData = Record<string, any>
-> = {
-  code: number;
-  message: string;
-  data: T;
-};
+service
+  .use(Interceptor())
+  .use(Versioning({ type: "header", defaultVersion: "1.0.0" }))
+  .use(Cache({ ttl: 60, l2: "localStorage" }))
+  .use(RequestPool({ concurrency: 4, maxQueue: 50, queueTimeout: 10000 }));
 ```
 
-### 定义返回类型
+`use()` 是同步且可链式调用的，插件名重复或依赖缺失会在调用时立即抛错。
 
-1. 定义后端标准数据格式
-
-```typescript
-export class CustomResponse {
-  status_code: number;
-  msg: string;
-}
-```
+请求池用来给并发设上限：浏览器的队列是先进先出、不可见、无法排优先级的，
+一个页面的并发爆发会把用户真正在等的那条请求挤到后面。它排在缓存**之后**，
+所以缓存能答的请求不会占用并发额度。
 
-2. 创建时应用格式
+## 请求策略
 
-```typescript
-// service.ts
-import { SnailServer, Server } from "@snail-js/api";
+```ts
+import { useDownload, useRequest } from "@snail-js/api/strategies";
 
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-class BackEnd extends SnailServer<CustomResponse> {}
+const { loading, data, error, send, bind } = useRequest(userApi.getUser);
+await send("1");
 
-export const Service = new BackEnd();
+// 下载：只 await「换取临时链接」的那次请求，文件本身交给浏览器原生下载
+const { download } = useDownload(reportApi.create);
+await download({ from: "2026-01-01" });
 ```
 
-3. 调用 API 时携带数据格式
+默认适配 Vue 的响应式状态（`ref`）；React 用户请从
+`@snail-js/api/strategies/react` 引入，无框架场景请从
+`@snail-js/api/strategies/plain` 引入。
 
-```typescript
-import { userApi } from "./user";
+不想把整个文件读进 JavaScript 内存时用 `useDownload`：它 await 的只是让服务端
+生成临时下载链接的那次请求，随后用 `<a>` 触发浏览器原生下载 —— 有进度、可断点
+续传、不占内存。`useDownload` 属于策略而非插件，因为它是一次明确的用户动作，
+而不是作用于所有请求的横切关注点。
 
-class User {
-  id: number;
-  name: string;
-  tel: string;
-  age: number;
-}
-
-const getUser = userApi.get<User>();
-const { send } = getUser;
-
-const res = await send("1");
-
-// 默认情况，以data为key存储数据
-// res.data => CustomResponse & { data : User}
-```
-
-> API 被调用的返回格式
+## 文档
 
-```typescript
-const getUser = userApi.get<User>();
-const { send } = getUser;
-const res = await send("1");
+完整文档：<https://snail-js.github.io/api>
 
-// res.data => CustomResponse & { data: User }
-
-const getUser = userApi.get<Blob>();
-const { send } = getUser;
-const res = await send("1");
-// res => AxiosResponse<Blob>
-```
-
-> `data: T`,后端响应数据；默认为`ResponseData<T = any>`类型；可由用户自定义修改
-
-> `error: null | Error` ; 请求过程中的错误包含在此，可先判断 error 是否为 null 再进行数据处理
-
-> `hitCache?: boolean`; 标识请求是否击中缓存；若从缓存获得数据，则不会发送请求。
-
-4. 若后端返回数据不是以 data 为 key 包含数据
-
-```typescript
-@Server({
-  baseURL: "/api",
-  timeout: 5000,
-})
-class BackEnd extends Snail<CustomResponse, "records"> {}
-
-const res = await userApi.get<User>();
-// 自定义数据key
-// res.data => CustomResponse & { records : User}
-```
+- [快速开始](https://snail-js.github.io/api/guide/getting-started)
+- [装饰器参考](https://snail-js.github.io/api/guide/decorators)
+- [插件生命周期](https://snail-js.github.io/api/guide/plugin-lifecycle)（[English](https://snail-js.github.io/api/guide/plugin-lifecycle_EN)）
+- [编写插件](https://snail-js.github.io/api/guide/plugin-authoring)
+- [从 0.1.x 迁移](https://snail-js.github.io/api/guide/migration)
 
-### 非 json 数据的返回
+## 设计说明
 
-- 若后端返回的 content-type 不是 json 类型，send 方法返回的将是`AxiosResponse`
-- 若后端返回的 content-type 是 json 类型，send 方法返回的将是`AxiosResponse.data`
+核心只负责三件事，其余全部是插件：
 
-### 代码仓库
+1. 装饰器写入的元数据；
+2. 请求管线；
+3. 插件生命周期（Koa 风格中间件 + 双向洋葱模型）。
 
-<p>
-  <a href="https://gitee.com/limich/snail">
-    <img src="https://img.shields.io/badge/snail-js?style=flat&label=gitee&labelColor=F56C6C&link=https%3A%2F%2Fgitee.com%2Flimich%2Fsnail"></img>
-  </a>
-</p>
-<p>
-  <a href="https://github.com/limingchang/snail">
-    <img src="https://img.shields.io/badge/snail-js?style=flat&label=github&labelColor=F56C6C&link=https%3A%2F%2Fgihub.com%2Flimingchang%2Fsnail"></img>
-  </a>
-</p>
+内置插件使用的公开 API 与第三方插件完全相同 —— 不存在内部特权通道。如果你在编写插件，
+请阅读[插件生命周期](https://snail-js.github.io/api/guide/plugin-lifecycle)（英文原文见
+[Plugin lifecycle](https://snail-js.github.io/api/guide/plugin-lifecycle_EN)）。
 
-### 作者
+## License
 
-- mc.lee
+[MIT](./LICENSE)