Skip to content

Latest commit

 

History

History
185 lines (123 loc) · 11.2 KB

README.md

File metadata and controls

185 lines (123 loc) · 11.2 KB
Raw

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 项目。如果使用 Java、C++ 等语言，可定制代码生成器支持
  • 支持高度定制化 通过复写内部方法，各种高度定制化需求都可以满足
  • 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，欢迎到 这里 留言。