Merge branch 'master' into feature/1.0.0

.github/workflows/vitepress.yml

@@ -0,0 +1,46 @@
+# workflow 名称，可以自定义
+name: Deploy GitHub Pages
+
+# 触发条件：在代码 push 到 master 分支后，自动执行该 workflow
+on:
+  push:
+    branches:
+      - master
+
+# 任务
+jobs:
+  build-and-deploy:
+    # 服务器环境：最新版 Ubuntu，也可以自定义版本
+    runs-on: ubuntu-latest
+    steps:
+      # 拉取代码
+      - name: Checkout
+        uses: actions/checkout@v2
+        with: 
+          fetch-depth: 0
+
+      # 设置 Node.js 版本
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v1
+        with:
+          node-version: "18.19.0"
+      # 安装pnpm
+      - name: Install pnpm
+        run: npm i [email protected] -g
+
+      # 如果缓存没有命中，安装依赖
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # 生成静态文件
+      - name: Build
+        run: pnpm docs:build
+
+      # 部署到 GitHub Pages
+      - name: Deploy
+        uses: crazy-max/ghaction-github-pages@v2
+        env:
+         GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }} # ACCESS_TOKEN 是创建的 Secret 名称，替换为你自己创建的名称
+        with:
+          target-branch: gh-pages # 部署到 gh-pages 分支，master 分支存放的是项目源码，而 gh-pages 分支则用来存放生成的静态文件
+          build_dir: docs/.vitepress/dist # vuepress 生成的静态文件存放的地方

.gitignore

@@ -2,4 +2,6 @@ dist/
 node_modules
 node_modules/
 .temp
-*.log
+*.log
+docs/.vitepress/cache/
+.vitepress/cache/

.husky/commit-msg

@@ -1,4 +1,5 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-npm run commitlint
+# npm run commitlint
+npx commitlint --config .commitlintrc.cjs --edit ${1}

docs/.vitepress/config.mts

@@ -0,0 +1,76 @@
+import { defineConfig } from 'vitepress';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: 'Applet Request',
+  description: 'Awesome Applet Request Library',
+  base: '/applet-request',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: '主页', link: '/' },
+      { text: '指南', link: '/guide/introduce/what-is-applet-request' },
+      { text: 'API', link: '/api/core' },
+    ],
+
+    sidebar: {
+      '/guide/': [
+        {
+          text: '介绍',
+          collapsed: false,
+          base: '/guide/introduce/',
+          items: [
+            { text: '什么是AppletRequest？', link: '/what-is-applet-request' },
+            { text: '开始使用', link: '/getting-started' },
+          ],
+        },
+        {
+          text: '核心概念',
+          collapsed: false,
+          base: '/guide/core/',
+          items: [
+            { text: '默认配置', link: '/default-config' },
+            { text: '中间件', link: '/middleware' },
+            { text: '适配器', link: '/adapter' },
+          ],
+        },
+        {
+          text: '适配器列表',
+          collapsed: false,
+          base: '/guide/adapters/',
+          items: [
+            { text: 'axios 适配器', link: '/axios' },
+            { text: 'uni.downloadFile 适配器', link: '/uniapp-downloadFile' },
+            { text: 'uni.request 适配器', link: '/uniapp-request' },
+            { text: 'uni.uploadFile 适配器', link: '/uniapp-uploadFile' },
+            { text: 'xhr 适配器', link: '/xhr' },
+          ],
+        },
+      ],
+      '/api/': [
+        {
+          text: 'packages',
+          base: '/api/',
+          items: [
+            {
+              text: '@applet-request/core',
+              link: '/core',
+            },
+            {
+              text: '@applet-request/adapters',
+              link: '/adapters',
+            },
+            {
+              text: '@applet-request/shared',
+              link: '/shared',
+            },
+          ],
+        },
+      ],
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
+    ],
+  },
+});

docs/api/adapters.md

@@ -0,0 +1 @@
+## 适配器API

docs/api/core.md

@@ -0,0 +1 @@
+## 核心API

docs/api/shared.md

@@ -0,0 +1 @@
+## 共享API

docs/guide/adapters/axios.md

@@ -0,0 +1,49 @@
+## 简介
+axios的适配器。
+
+## 使用
+```typescript
+import { HttpRequest } from '@applet-request/core';
+import type { AxiosConfig } from '@applet-request/adapters';
+import { AxiosAdapter } from '@applet-request/adapters';
+
+/**
+ * 定义的公共响应类型，可以不传
+ */
+interface CommonResponse {
+  /**
+   * 业务状态码
+   */
+  code: number;
+  /**
+   * 业务信息
+   */
+  message: string;
+}
+
+// 创建请求实例，使用axios的适配器
+const requestInstance = new HttpRequest(new AxiosAdapter<CommonResponse>());
+
+// 设置默认请求配置
+requestInstance.setDefaultConfig({
+  baseURL: '', // 这里改为你的业务接口前缀
+});
+
+/**
+ * 请求默认响应格式，可以根据你的业务特性替换为你的
+ */
+export interface RequestResponse<Response> extends CommonResponse {
+  data: Response;
+}
+
+/**
+ * 基础请求方法
+ * @param options 请求参数
+ * @returns 返回服务端的服务响应内容
+ */
+export function request<Response = never>(options: AxiosConfig) {
+  return requestInstance.request<
+    Response extends never ? CommonResponse<Response> : RequestResponse<Response>
+  >(options);
+}
+```

docs/guide/adapters/uniapp-downloadFile.md

@@ -0,0 +1,26 @@
+## 简介
+uni.downloadFile的适配器。
+
+## 使用
+```typescript
+import { HttpRequest } from '@applet-request/core';
+import type { UniDownloadFileConfig } from '@applet-request/adapters';
+import { UniDownloadFileAdaptor } from '@applet-request/adapters';
+
+// 创建请求实例，使用uniapp的下载适配器
+const requestInstance = new HttpRequest(new UniDownloadFileAdaptor());
+
+// 设置默认请求配置
+requestInstance.setDefaultConfig({
+  baseURL: '', // 这里改为你的业务接口前缀
+});
+
+/**
+ * 基础请求方法
+ * @param options 请求参数
+ * @returns 返回服务端的服务响应内容
+ */
+export function request(options: UniDownloadFileConfig) {
+  return requestInstance.request(options);
+}
+```

docs/guide/adapters/uniapp-request.md

@@ -0,0 +1,49 @@
+## 简介
+uni.request的适配器。
+
+## 使用
+```typescript
+import { HttpRequest } from '@applet-request/core';
+import type { UniRequestConfig } from '@applet-request/adapters';
+import { UniRequestAdapter } from '@applet-request/adapters';
+
+/**
+ * 定义的公共响应类型，可以不传
+ */
+interface CommonResponse {
+  /**
+   * 业务状态码
+   */
+  code: number;
+  /**
+   * 业务信息
+   */
+  message: string;
+}
+
+// 创建请求实例，使用uniapp的请求适配器
+const requestInstance = new HttpRequest(new UniRequestAdapter<CommonResponse>());
+
+// 设置默认请求配置
+requestInstance.setDefaultConfig({
+  baseURL: '', // 这里改为你的业务接口前缀
+});
+
+/**
+ * 请求默认响应格式，可以根据你的业务特性替换为你的
+ */
+export interface RequestResponse<Response> extends CommonResponse {
+  data: Response;
+}
+
+/**
+ * 基础请求方法
+ * @param options 请求参数
+ * @returns 返回服务端的服务响应内容
+ */
+export function request<Response = never>(options: UniRequestConfig) {
+  return requestInstance.request<
+    Response extends never ? CommonResponse<Response> : RequestResponse<Response>
+  >(options);
+}
+```

docs/guide/adapters/uniapp-uploadFile.md

@@ -0,0 +1,49 @@
+## 简介
+uni.uploadFile的适配器。
+
+## 使用
+```typescript
+import { HttpRequest } from '@applet-request/core';
+import type { UniUploadFileConfig } from '@applet-request/adapters';
+import { UniUploadFileAdaptor } from '@applet-request/adapters';
+
+/**
+ * 定义的公共响应类型，可以不传
+ */
+interface CommonResponse {
+  /**
+   * 业务状态码
+   */
+  code: number;
+  /**
+   * 业务信息
+   */
+  message: string;
+}
+
+// 创建请求实例，使用uniapp的文件上传适配器
+const requestInstance = new HttpRequest(new UniUploadFileAdaptor<CommonResponse>());
+
+// 设置默认请求配置
+requestInstance.setDefaultConfig({
+  baseURL: '', // 这里改为你的业务接口前缀
+});
+
+/**
+ * 请求默认响应格式，可以根据你的业务特性替换为你的
+ */
+export interface RequestResponse<Response> extends CommonResponse {
+  data: Response;
+}
+
+/**
+ * 基础请求方法
+ * @param options 请求参数
+ * @returns 返回服务端的服务响应内容
+ */
+export function request<Response = never>(options: UniUploadFileConfig) {
+  return requestInstance.request<
+    Response extends never ? CommonResponse<Response> : RequestResponse<Response>
+  >(options);
+}
+```

docs/guide/core/adapter.md

@@ -0,0 +1,53 @@
+## 什么是适配器？
+此处使用了适配器设计模式，适配器是当前请求的核心概念，请求库的core部分是与框架/平台无关的实现，我们需要根据core提供的核心抽象类进行适配各个不同的框架/平台，用于抹平差异。
+
+## 官方提供的适配器
+| 适配器 | 说明 |
+| ------- | ----------- |
+| [AxiosAdapter](/guide/adapters/axios) | 适配axios |
+| [UniDownloadFileAdaptor](/guide/adapters/uniapp-downloadFile) | 适配uni.downloadFile |
+| [UniRequestAdapter](/guide/adapters/uniapp-request) | 适配uni.request |
+| [UniUploadFileAdaptor](/guide/adapters/uniapp-uploadFile) | 适配uni.uploadFile |
+| [XHROtherConfig](/guide/adapters/xhr) | 适配xhr |
+
+## 如何自己编写适配器？
+```typescript
+import { Adapter } from '@applet-request/core';
+import type {
+  RequestContext,
+  MiddlewareNext,
+  RequestConfig,
+} from '@applet-request/core';
+
+/**
+ * 你的其他请求适配配置
+ */
+export type XxxRequestOtherConfig = {};
+
+/**
+ * xxx的请求配置
+ */
+export type XxxRequestConfig = RequestConfig<XxxConfig>;
+
+/**
+ * 你需要适配的请求回调原串类型
+ */
+export type RequestSuccessCallbackResult = {};
+
+/**
+ * uni.request的请求适配器
+ */
+export class XxxRequestAdapter<Data> extends Adapter<
+XxxRequestOtherConfig,
+Data,
+RequestSuccessCallbackResult
+> {
+  async request(context: RequestContext<XxxRequestOtherConfig, Data, RequestSuccessCallbackResult>, next: MiddlewareNext): Promise<unknown> {
+    await next();
+    return new Promise((resolve, reject) => {
+      // 你的适配逻辑
+    });
+  }
+}
+
+```