约定式接口编译时转换插件

@umijs/plugin-transform-api

本篇 README.md 面向开发者

简介

插件功能作用于约定式API接口配置的编译时转换，为umijs提供接口转换能力，开发者不再需要进行频繁的手写service spi 函数。插件会自动帮您转换成对应的Promise<R>的函数，只需要从plugin或者是umi中引用就可以完成接口请求的问题。

插件相对来说是在编译时完成的，相对来说，会比运行时处理约定式接口承诺减少了多余的开销，利用umijs脚手架的微内核能力可以做到可拔插，剔除打包依赖的作用。

配置 -> 接口函数 -> umi

使用方法

通过包管理工具安装当前插件到运行时以来，安装结束后可以在package.json的devDependencies中可以查看当前版本依赖。

# yarn
yarn add plugin-interface -D

# npm
npm install plugin-interface -D

添加插件

根据相应的开发配置引入插件，一般在.umirc.ts 或者 config/*下配置对应的配置可以对应注入相应功能。参考以下配置:

export default defineConfig({
  plugins: ['plugin-interface'],
  nodeModulesTransform: {
    type: 'none',
  },
  routes: [{ path: '/', component: '@/pages/index' }],
  fastRefresh: {},
  interface: {
    path: 'services',
    requestPath: '@/utils/request',
  },
});

相对应插件会在开发时监听对应文件夹下的文件，并且产生最新的函数接口。

参数配置

| 名称 | 类型 | 描述 | 默认值 | | --- | --- | --- | --- | | path | string | 定义目标当前需要监听的路径地址，默认配置为api | api | | requestPath | string | 接口请求函数的页面地址，最终映射到import()当中使用 | __ | | ... | any | 待添加 | __ |

添加一个配置

如何添加一个最基本的配置来运行脚本添加工具？使用起来是非常方便的。

JSON 格式文件

{
  "getUserInfo": "POST /mall-port/user/info",
  "login": "POST /mall-port/user/login",
  "deleteUser": "POST /mall-port/user/:id"
}

JS & TS 文件

module.export = {
  getUserInfo: "POST /mall-port/user/info",
  login: "POST /mall-port/user/login",
  deleteUser: "POST /mall-port/user/:id"
}

使用以上两种参数行为会为您在.umi/plugin-interface下生成新的插件函数，且默认配置为export方式。同时会将其export的内容导入到umi的导出项内。

// @ts-nocheck
import request from 'umi-request'

export function getUserInfo <T = any, O = Record<string, any>, R = any>(
  payload?: T = {},
  options?: O = {},
): Promise<R> {

    /* [info]: @no link params */

  return request( `/mall-port/user/info`, {
    data: payload,
    method: 'POST',
    ...options
  })
}


export function login <T = any, O = Record<string, any>, R = any>(
  payload?: T = {},
  options?: O = {},
): Promise<R> {

    /* [info]: @no link params */

  return request( `/mall-port/user/login`, {
    data: payload,
    method: 'POST',
    ...options
  })
}


export function deleteUser <T = any, O = Record<string, any>, R = any>(
  payload?: T = {},
  options?: O = {},
): Promise<R> {

    const { id, ...data } = payload

  return request( `/mall-port/user/${id}`, {
    data: data,
    method: 'POST',
    ...options
  })
}

如何引用

当有了一份基于typeScript的接口函数，可以通过以下两种方式进行引入。默认来说当前的文件是使用typescript的，同时也希望尽量使用这些api，能够有更多的提示性。

import { deleteUser } from 'umi'

deleteUser().then()

import { deleteUser } from '@@/plugin-interface/api'
deleteUser().then()

TypeScript 支持

默认的接口函数都是TypeScript格式写的。如果需要指定类型推导来说，目前来说是支持的。暂时给与了T, O, R三个泛型推导函数

• T：当前传入payload传递进来的类型，也就是接口函数需要的一些类型。
• O：当前接口内置的config设置，可以自己定义一些method, header的一些自定义行为。最常见就是更改接口请求的数据方式。
• R：当前Promise的返回值，一般为resoponse。数据格式为后端接口请求的响应。

如果需要使用Typescript将启用严格类型模式，请确保类型声明推导的正确合理性。

如何参与开源项目

1. 克隆当前仓库
2. 创建你自己的开发分支(git checkout -b [your branch name])
3. 提交你的代码修改 (git commit -m 'Add some AmazingFeature')
4. 推送到Github仓库 (git push origin feature/AmazingFeature)
5. 与我联系后，打开一个PR(Pull Request)推送给我。
6. 一星期后会进行仓库branch merge

贡献者

• @wangly19

开源协议

• 查看开源协议：MIT

联系我 & 技术探讨

• 微信：Rzicon：验证内容填写：umi插件
• 加入技术研讨群：

资源

• umijs 中文文档
• umijs 插件最佳实践
• umijs 插件系统
• 掘金社区