thx / rapper

一个自带类型的请求库

[![MIT License][license-shield]][license-url]

一个自带类型的请求库

文档

Rapper 是什么？

Rapper 是 TypeScript 的最佳拍档，它可以帮你生成具有类型定义的请求方案。

• 无需自行书写请求代码，把 HTTP 接口当做函数调用
• 请求参数/返回数据类型化，静态校验、自动补全快到飞起
• 对 React/Redux 特别优化，提供全局数据方案，hooks 轻松使用

来自阿里的 THX 团队

十年前我们创立了 Rap 项目，如今已经有相当多的用户在 Rap 中管理接口文档和 Mock 数据。

Rapper 在此基础上更进一步，利用这些已经录入的接口数据为你生成 TypeScript 类型定义以及配套的数据请求方案，让你在代码开发中省去重复的劳动。

快速开始

0. 如果你还没使用过 Rap，请先去我们的官方站点：http://rap2.taobao.org/ 注册一个账户并新建一个仓库，再向下进行。

1. 进入仓库，点击配置「生成 TS 代码」

2. 按照指引把 Rapper 安装到项目中

3. 执行 npm run rapper 生成代码

4. 引入生成的 fetch 函数，调用它就能发起请求并返回带有类型的响应数据

// 从生成的代码中引入 fetch
import { fetch } from './rapper';
// 直接使用 fetch 调用请求函数，能获得请求/返回类型校验/提示
(async function() {
  // alt+点击可以查看接口信息
  const res = await fetch['GET/example/rapper']({
    foo: '123',
  });
  const nameList = res.taskList.map(e => e.name);
})();

友好的类型约束/提示

随时跳转到 Rap 查看接口文档

在 React/Redux 场景下强大的数据管理方案

如果你使用 React 和 Redux，在以上基础的请求函数之外，Rapper 还为你提供精心设计过的全局数据管理方案。

以往发送一个请求要写繁杂的 interface/action/reducer/effect，现在这些都会为你准备好，你只需要一行代码即可：

const [responseData, { isPending, errorMessage }] = useAPI['GET/duck/fetchColor'](requestParams);

文档

想要在生产中深度使用 Rapper，你可能还需要自定义请求函数、对返回的数据做统一的类型转换

具体请参考我们的文档：https://www.yuque.com/rap/rapper

社区贡献

• @antmjs/rapper 基于 Rapper 开发，使配置更灵活，同时增加本地类型同步远程文档重要功能

联系我们

• Github Issue
• 钉钉群：11789704

rapper's Issues

当根结点是数组时，会生成_root_层级

当根结点是数组时，会生成_root_层级

如在rap2中导入[{a: 1}, {a: 2}]时
rapper生成代码的interface 会变成

Res: {
      _root_: {
            a: number;
      }[]
}

无法导入swagger的数据

操作步骤：
1：导出apifox的接口数据为，swagger2.0格式

数据如下：
{"openapi":"3.0.1","info":{"title":"hippo","description":"","version":"1.0.0"},"tags":[],"paths":{"/tasks-notifications":{"get":{"summary":"获取通知&待办&个人信息","deprecated":false,"description":"获取当前用户消息数量、待办内容、个人信息","tags":[],"parameters":[{"name":"workNo","in":"query","description":"工号","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"string"},"errorCode":{"type":"string"},"errorLevel":{"type":"string"},"errorMsg":{"type":"string"},"content":{"type":"object","properties":{"tasks":{"type":"object","properties":{"count":{"type":"integer","description":"Number of pending tasks"},"data":{"type":"array","items":{"type":"object","properties":{"creatorWorkNo":{"type":"string","description":"Creator's Work Number"},"creatorName":{"type":"string","description":"Creator's Name"},"creatorAvatar":{"type":"string","description":"Creator's Avatar"},"assigneeWorkNo":{"type":"string","description":"Assignee's Work Number"},"assigneeName":{"type":"string","description":"Assignee's Name"},"assigneeAvatar":{"type":"string","description":"Assignee's Avatar"},"taskCenterCode":{"type":"string","description":"Message Code"},"title":{"type":"string","description":"Message Title"},"sourceCode":{"type":"string","description":"Source System Code"},"sourceName":{"type":"string","description":"Source System Name"},"isAgent":{"type":"string","description":"Is Agent Approval"},"url":{"type":"string","description":"Redirect URL"}},"required":["creatorWorkNo","creatorName","creatorAvatar","assigneeWorkNo","assigneeName","assigneeAvatar","taskCenterCode","title","sourceCode","sourceName","isAgent","url"]}}}},"notifications":{"type":"object","properties":{"count":{"type":"integer","description":"Number of notifications"}}},"personInfo":{"type":"object","properties":{"avatar":{"type":"string","description":"Avatar"},"displayName":{"type":"string","description":"For formal employees: Name (Nickname)\nFor informal employees: Name (Work Number)"},"briefs":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Title"},"titleEn":{"type":"string","description":"Title in English"},"linkUrl":{"type":"string","description":"Redirect URL, supports internal/external path access and full domain access"}}}}}}}}},"required":["success","errorCode","content"]}}}}},"security":[]}}},"components":{"schemas":{},"securitySchemes":{}},"servers":[]}
2、导入到rap平台

3、提交显示成功，但是返回后的页面没有导入的数据

建议生成的 fetch 对象中, 使用泛型来约束类型, 而不是属性

目前生成的代码大概是这样:

export interface IModels {
  'GET/welcome': {
    Req: {},
    Res: {},
  }
}

export const createFetch() {
  return {
    'GET/welcome': (input) => doFetch('GET', '/welcome', input),
    // ...
  }
}

export const fetch = createFetch()

这样会生成大量的没有意义的 api 实例函数(createFetch 函数内返回的对象在编译成 js 后依旧存在), 建议改成这样:

export interface IModels {
  'GET/welcome': {
    Req: {},
    Res: {},
  }
}

export function fetch<K extends keyof IModels>(key: K, input: IModels[K]['Req']): Promise<IModels[K]['Res']> {
  const pos = key.indexOf('/')
  const method = key.substr(0, pos)
  const url = key.substr(pos)

  return doFetch(method, url, input)
}

这样生成的 js 代码就只有一个 fetch 实例了, 会简单很多, 并且 IDE 在提示的时候, 对函数参数的支持会比 ['GET/welcome'] 这种形式更友好.

无法区分query和body的参数

无法区分query和body的参数

无论在rap2上设置query或者body他都作为params进入

可以实现一个类似于导出功能，每次导出的时候生成ts文件并下载吗

post请求, 路径参数怎么替换掉啊

这样是无效的

request["POST/data-api/v1/nodes/{node_id}/products"]({node_id: '123' ...rest})

helper!!!

不管是overrideFetch还是createFetch，headers选项设置不起作用

不管是overrideFetch还是createFetch，把headers设置成 application/x-www-form-urlencoded 都不起作用，只有写在fetch的第二个参数中有用，且content-type属性必需是小驼峰contentType才行

以下代码设置后是不起作用的：

export const fetch = createFetch(
  {
    /** 'prefix' 前缀，统一设置 url 前缀，默认是 '' */
    // prefix: 'https://rap2api.taobao.org/app/mock/3402',
    fetchOption: {
      /** 全局配置请求 content-type，默认是 'application/json' */
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },

      credentials: 'same-origin',
    },
  },
  { fetchType: FetchType.AUTO },
);

以下代码设置是可以的:

fetch['POST/api/detail'](
      { uid: 1 },
      {
        contentType: 'application/x-www-form-urlencoded',
      }
)

字符串字面量的联合类型，用mockjs占位符@pick(['A','B','C'])，识别不了

接口配置该字段（三选一）

期望识别成：indexType: 'A' | 'B' | 'C'类型
现在还是识别成 indexType: string

能否自动生成js文件?