|
| 1 | + |
| 2 | +<div align="center"> |
| 3 | + |
| 4 | +[](https://github.com/alibaba/pont) |
| 5 | + |
| 6 | +# Pont - 搭建前后端之桥 |
| 7 | + |
| 8 | +[](https://www.npmjs.com/package/pont-engine) |
| 9 | +[](https://www.npmjs.com/package/pont-engine) |
| 10 | +[](https://github.com/alibaba/pont/blob/master/LICENSE) |
| 11 | +[](https://gitter.im/jasonHzq/pont-engine?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +</div> |
| 16 | + |
| 17 | +pont 在法语中是“桥”的意思，寓意着前后端之间的桥梁。Pont 把 swagger、rap、dip 等多种接口文档平台，转换成 Pont 元数据。Pont 利用接口元数据，可以高度定制化生成前端接口层代码，接口 mock 平台和接口测试平台。 |
| 18 | + |
| 19 | +其中 swagger 数据源，Pont 已经完美支持。并在一些大型项目中使用了近两年，各种高度定制化需求都可以满足。 |
| 20 | + |
| 21 | +Pontx 用户请访问 [Pontx](https://github.com/pontjs/pontx) |
| 22 | + |
| 23 | +## ✨特性 |
| 24 | + |
| 25 | +- **跨语言** 天然支持 Javascript 项目及 Typescript 项目。如果使用 `Java`、`C++` 等语言，可定制代码生成器支持 |
| 26 | +- **支持高度定制化** 通过复写内部方法，各种高度定制化需求都可以满足 |
| 27 | +- **VSCode 插件支持** 专门为 Pont 开发的 VSCode 插件 vscode-pont，完美支持 Pont 所有能力 |
| 28 | +- **丰富的命令行**提供丰富的命令行命令，满足不同场景的使用 |
| 29 | +- **自动化 mocks 服务**Pont 自动生成所有 mocks 数据，并提供所有接口的 mocks 服务 |
| 30 | + |
| 31 | +## ⚡快速开始 |
| 32 | + |
| 33 | +### 1. 安装 |
| 34 | + |
| 35 | +全局安装 pont-engine |
| 36 | + |
| 37 | +```bash |
| 38 | +# 选择一个你喜欢的包管理器 |
| 39 | + |
| 40 | +# NPM |
| 41 | +$ npm i -g pont-engine |
| 42 | + |
| 43 | +# Yarn |
| 44 | +$ yarn global add pont-engine |
| 45 | + |
| 46 | +# pnpm |
| 47 | +$ pnpm add -g pont-engine |
| 48 | +``` |
| 49 | + |
| 50 | +### 2. 初始化 |
| 51 | + |
| 52 | +使用 `pont start` 命令，快速创建初始模板 |
| 53 | + |
| 54 | + |
| 55 | +### 3. 安装 VSCode 插件 |
| 56 | + |
| 57 | +打开 VSCode 插件商店，输入 `vscode-pont` 搜索安装 |
| 58 | + |
| 59 | + |
| 60 | +#### |
| 61 | + |
| 62 | +### 4. 沉浸式接口开发 |
| 63 | + |
| 64 | +插件安装成功后，点击 Pont 图标，打开面板进行进一步操作。更多插件相关请参考 [插件文档](https://marketplace.visualstudio.com/items?itemName=jasonHzq.vscode-pont) |
| 65 | + |
| 66 | + |
| 67 | +点击接口代码片段图标，打开接口列表，搜索后生成接口代码片段，快速开始接口开发 |
| 68 | + |
| 69 | + |
| 70 | +### 5. 联调维护 |
| 71 | + |
| 72 | +实时发现后端接口更新 |
| 73 | + |
| 74 | +更新接口层后，可迅速定位接口调用代码，进行调用修改。 |
| 75 | + |
| 76 | + |
| 77 | +### 6. 自定义 |
| 78 | + |
| 79 | +Pont 支持自定义**数据获取 、数据源预处理、自定义代码生成器**等。请参考 [定制化 Pont](./docs/customizedPont.md) |
| 80 | + |
| 81 | +### 7. 提示 |
| 82 | + |
| 83 | +- 确保服务端使用 Swagger（目前只支持 Swagger V2、V3），提供的数据源接口是免登录的。如果不是，请后端帮忙简单配置一下，或者使用 [fetchMethodPath 配置](./docs/customizedPont.md#fetchmethodpath)，通过自定义**数据获取**来获取带鉴权的接口的文档。 |
| 84 | +- 若需替换默认的请求信息，请参阅 [pontCore](https://github.com/alibaba/pont/tree/master/docs/pontCore.md)。 |
| 85 | + |
| 86 | +## 🔍 文档 |
| 87 | + |
| 88 | +[命令行](./docs/CMD.md) |
| 89 | + |
| 90 | +[标准数据源模型](./docs/standardDataSource.md) |
| 91 | + |
| 92 | +[pont-config.josn 配置项](./docs/pontConfig.md) |
| 93 | + |
| 94 | +[定制化 Pont](./docs/customizedPont.md) |
| 95 | + |
| 96 | +[VSCode 插件](https://marketplace.visualstudio.com/items?itemName=jasonHzq.vscode-pont) |
| 97 | + |
| 98 | +## 自动化 mocks 服务 |
| 99 | + |
| 100 | +mocks.enable 配置为 true，pont 将自动生成所有 mocks 数据，并提供所有接口的 mocks 服务。此外 IDE 提供如下功能 |
| 101 | + |
| 102 | +- 右键 pont 接口代码，可以跳转(jump to mock position)去编辑接口的 mocks 数据 |
| 103 | +- 右键 pont 接口代码，可以访问(visit mocks interface) GET 类型的 mocks 接口。 |
| 104 | + |
| 105 | +mocks 自动生成所有 mocks 数据，你也可以自由更新 mocks 数据，支持 [mockjs](http://mockjs.com/examples.html) 语法更新 mocks 数据。 |
| 106 | + |
| 107 | +## demo |
| 108 | + |
| 109 | +参考下面的例子，来体验 pont。 |
| 110 | + |
| 111 | +- [pont-demo](https://github.com/nefe/pont-demo) |
| 112 | +- [nuxt-ts-pont-demo](https://github.com/gaoletian/nuxt-ts-pont-demo) |
| 113 | + |
| 114 | +## 👍 最佳实践 |
| 115 | + |
| 116 | +- 项目 pre-commit hook 中，加上 pont check，防止本地数据源被研发人员损坏。 |
| 117 | +- 很多 Swagger 所有的接口返回的类型都类似是 Result，主要是囊括了约定的接口错误字段，类似 `{ errorCode: 0, data: T, errMessage: '' }`。这里建议，让后端 Swagger 的接口返回类型，去掉这个 Result 外壳。只返回 data 的 T 类型。 |
| 118 | +- vscode 配置 `trigger suggest` 的快捷键(cmd K + cmd S)，传参时，用快捷键触发提醒，非常好用； |
| 119 | +- pont template 配置 API、defs 为全局变量；这样不需要 import 任何接口、实体类；使用 API 直接触发建议找到 模块、接口，非常方便 |
| 120 | +- 快捷键 cmd + ctrl + p 进行接口查找，非常方便； |
| 121 | +- 善于利用实体类（defs），可以当成类型用、也可以作为逻辑实现的辅助；实体类是后端写得实体类，前端自己写实体类，既没有必要，长期来看也会和后端的实现差异越来越大。如果有自定义逻辑，继承 defs 实体类即可。 |
| 122 | +- redux 项目，建议结合 [https://github.com/nefe/iron-redux](https://github.com/nefe/iron-redux)，一个致力类型完美和去冗余的轻量化 redux 库。例如类型友好的，运行安全的 get 方法：[https://github.com/nefe/iron-redux#safeget](https://github.com/nefe/iron-redux#safeget) |
| 123 | + |
| 124 | +## ❓常见问题 |
| 125 | + |
| 126 | +1. demo 中，生成代码的 pontFetch 函数，是要自己实现的吗？ |
| 127 | +答：pontFetch 是用户自己项目的请求公共方法。因为每个项目的接口有自己的业务逻辑，比如如何判断接口返回的结果是否正确，所以 pont 的默认模板并没有自己实现一套 fetch 方法。另外 Pont 生成的代码是可以用自定义模板配置的。可以在模板上更改 pontFetch 的引用路径和名字。 |
| 128 | +1. nestjs 搭配的 Swagger JSON 生成出来的 pont 文件为什么没有 mods? |
| 129 | +答：nestjs 中的 Swagger 必须在每个 Controller 上添加 ApiUseTags 装饰器，并且在每个控制器的方法上添加 ApiOperation 装饰器 才能正确输出带 Tags 以及 operationId 的 Swagger JSON。Tags 和 operationId 是 pont 必需的（@nestjs/swagger 自动生成的 default Tags 暂时不被兼容）。 |
| 130 | +示例如下 (`@nestjs/swagger@^3`) |
| 131 | +对于 `@nestjs/swagger@^4`，需要如下配置来手动注册 Tag |
| 132 | + |
| 133 | +``` |
| 134 | +import { Controller } from '@nestjs/common'; |
| 135 | +import { ApiUseTags, ApiOperation, ApiOkResponse } from '@nestjs/swagger'; |
| 136 | +
|
| 137 | +@ApiUseTags('pet') |
| 138 | +@Controller('pet') |
| 139 | +export class PetController { |
| 140 | + @ApiOperation({ title: 'getDog', operationId: 'getDog' }) |
| 141 | + @Get() |
| 142 | + getDog() {} |
| 143 | +} |
| 144 | +``` |
| 145 | + |
| 146 | +```typescript |
| 147 | +// ... |
| 148 | +const options = new DocumentBuilder().setTitle('your app').addTag('pet').build(); |
| 149 | +const document = SwaggerModule.createDocument(app, options); |
| 150 | +SwaggerModule.setup('/api', app, document); |
| 151 | +``` |
| 152 | + |
| 153 | +3. API、defs 全局变量找不到 |
| 154 | +答：将 pont 生成的 api.d.ts 塞到 tsconfig.json 中的 includes 数组最前面。并在项目入口处 import pont 生成的入口文件。 |
| 155 | + |
| 156 | +```json |
| 157 | +{ |
| 158 | + "compilerOptions": { |
| 159 | + "allowJs": true, |
| 160 | + "checkJs": true, |
| 161 | + "outDir": "./**" |
| 162 | + }, |
| 163 | + "include": ["./services/api.d.ts", "./src"], |
| 164 | + "exclude": [] |
| 165 | +} |
| 166 | + |
| 167 | +``` |
| 168 | + |
| 169 | +## 其它接口平台接入 |
| 170 | + |
| 171 | +目前 pont 支持 [Swagger](https://swagger.io/) V2 V3 三种数据源。其他类型数据源只需要在 scripts 中添加对应的数据格式转换文件，把对应数据格式转换为 pont 标准格式，即可适配新的数据源类型。希望社区可以踊跃贡献代码，接入更多类型的数据源！ |
| 172 | + |
| 173 | +## 钉钉用户群 |
| 174 | + |
| 175 | +群号：33661609 |
| 176 | + |
| 177 | +## 🎉 谁在使用 |
| 178 | + |
| 179 | +- 阿里巴巴 |
| 180 | + |
| 181 | +> 我们在这里列出了部分使用者，如果你的公司和产品使用了 Pont，欢迎到 [这里](https://github.com/alibaba/pont/issues/301) 留言。 |
0 commit comments