Skip to content

alibaba/pont

Repository files navigation

Pont logo

Pont - 搭建前后端之桥

npm version npm downloads GitHub license Gitter

Pont Process

pont 在法语中是“桥”的意思,寓意着前后端之间的桥梁。Pont 把 swagger、rap、dip 等多种接口文档平台,转换成 Pont 元数据。Pont 利用接口元数据,可以高度定制化生成前端接口层代码,接口 mock 平台和接口测试平台。

其中 swagger 数据源,Pont 已经完美支持。并在一些大型项目中使用了近两年,各种高度定制化需求都可以满足。

Pontx 用户请访问 Pontx

✨特性

  • 跨语言 天然支持 Javascript 项目及 Typescript 项目。如果使用 JavaC++ 等语言,可定制代码生成器支持
  • 支持高度定制化 通过复写内部方法,各种高度定制化需求都可以满足
  • VSCode 插件支持 专门为 Pont 开发的 VSCode 插件 vscode-pont,完美支持 Pont 所有能力
  • 丰富的命令行提供丰富的命令行命令,满足不同场景的使用
  • 自动化 mocks 服务Pont 自动生成所有 mocks 数据,并提供所有接口的 mocks 服务

⚡快速开始

1. 安装

全局安装 pont-engine

# 选择一个你喜欢的包管理器

# NPM
$ npm i -g pont-engine

# Yarn
$ yarn global add pont-engine

# pnpm
$ pnpm add -g pont-engine

2. 初始化

使用 pont start 命令,快速创建初始模板 test9.gif

3. 安装 VSCode 插件

打开 VSCode 插件商店,输入 vscode-pont 搜索安装 image.png

4. 沉浸式接口开发

插件安装成功后,点击 Pont 图标,打开面板进行进一步操作。更多插件相关请参考 插件文档 image.png

点击接口代码片段图标,打开接口列表,搜索后生成接口代码片段,快速开始接口开发 test12.gif

5. 联调维护

实时发现后端接口更新 image.png 更新接口层后,可迅速定位接口调用代码,进行调用修改。 image.png

6. 自定义

Pont 支持自定义数据获取 、数据源预处理、自定义代码生成器等。请参考 定制化 Pont

7. 提示

  • 确保服务端使用 Swagger(目前只支持 Swagger V2、V3),提供的数据源接口是免登录的。如果不是,请后端帮忙简单配置一下,或者使用 fetchMethodPath 配置,通过自定义数据获取来获取带鉴权的接口的文档。
  • 若需替换默认的请求信息,请参阅 pontCore

🔍 文档

命令行

标准数据源模型

pont-config.json 配置项

定制化 Pont

VSCode 插件

自动化 mocks 服务

mocks.enable 配置为 true,pont 将自动生成所有 mocks 数据,并提供所有接口的 mocks 服务。此外 IDE 提供如下功能

  • 右键 pont 接口代码,可以跳转(jump to mock position)去编辑接口的 mocks 数据
  • 右键 pont 接口代码,可以访问(visit mocks interface) GET 类型的 mocks 接口。

mocks 自动生成所有 mocks 数据,你也可以自由更新 mocks 数据,支持 mockjs 语法更新 mocks 数据。

demo

参考下面的例子,来体验 pont。

👍 最佳实践

  • 项目 pre-commit hook 中,加上 pont check,防止本地数据源被研发人员损坏。
  • 很多 Swagger 所有的接口返回的类型都类似是 Result,主要是囊括了约定的接口错误字段,类似 { errorCode: 0, data: T, errMessage: '' }。这里建议,让后端 Swagger 的接口返回类型,去掉这个 Result 外壳。只返回 data 的 T 类型。
  • vscode 配置 trigger suggest 的快捷键(cmd K + cmd S),传参时,用快捷键触发提醒,非常好用;
  • pont template 配置 API、defs 为全局变量;这样不需要 import 任何接口、实体类;使用 API 直接触发建议找到 模块、接口,非常方便
  • 快捷键 cmd + ctrl + p 进行接口查找,非常方便;
  • 善于利用实体类(defs),可以当成类型用、也可以作为逻辑实现的辅助;实体类是后端写得实体类,前端自己写实体类,既没有必要,长期来看也会和后端的实现差异越来越大。如果有自定义逻辑,继承 defs 实体类即可。
  • redux 项目,建议结合 https://github.com/nefe/iron-redux,一个致力类型完美和去冗余的轻量化 redux 库。例如类型友好的,运行安全的 get 方法:https://github.com/nefe/iron-redux#safeget

❓常见问题

  1. demo 中,生成代码的 pontFetch 函数,是要自己实现的吗? 答:pontFetch 是用户自己项目的请求公共方法。因为每个项目的接口有自己的业务逻辑,比如如何判断接口返回的结果是否正确,所以 pont 的默认模板并没有自己实现一套 fetch 方法。另外 Pont 生成的代码是可以用自定义模板配置的。可以在模板上更改 pontFetch 的引用路径和名字。
  2. nestjs 搭配的 Swagger JSON 生成出来的 pont 文件为什么没有 mods? 答:nestjs 中的 Swagger 必须在每个 Controller 上添加 ApiUseTags 装饰器,并且在每个控制器的方法上添加 ApiOperation 装饰器 才能正确输出带 Tags 以及 operationId 的 Swagger JSON。Tags 和 operationId 是 pont 必需的(@nestjs/swagger 自动生成的 default Tags 暂时不被兼容)。 示例如下 (@nestjs/swagger@^3) 对于 @nestjs/swagger@^4,需要如下配置来手动注册 Tag
import { Controller } from '@nestjs/common';
import { ApiUseTags, ApiOperation, ApiOkResponse } from '@nestjs/swagger';

@ApiUseTags('pet')
@Controller('pet')
export class PetController {
  @ApiOperation({ title: 'getDog', operationId: 'getDog' })
  @Get()
  getDog() {}
}
// ...
const options = new DocumentBuilder().setTitle('your app').addTag('pet').build();
const document = SwaggerModule.createDocument(app, options);
SwaggerModule.setup('/api', app, document);
  1. API、defs 全局变量找不到 答:将 pont 生成的 api.d.ts 塞到 tsconfig.json 中的 includes 数组最前面。并在项目入口处 import pont 生成的入口文件。
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "outDir": "./**"
  },
  "include": ["./services/api.d.ts", "./src"],
  "exclude": []
}

其它接口平台接入

目前 pont 支持 Swagger V2 V3 三种数据源。其他类型数据源只需要在 scripts 中添加对应的数据格式转换文件,把对应数据格式转换为 pont 标准格式,即可适配新的数据源类型。希望社区可以踊跃贡献代码,接入更多类型的数据源!

钉钉用户群

群号:33661609

🎉 谁在使用

我们在这里列出了部分使用者,如果你的公司和产品使用了 Pont,欢迎到 这里 留言。