v3-admin-vite 整合 Pont 引擎：从安装到请求适配

作者：纸飞机时间：2026-10-31 12:26:35浏览：527

本文详细记录了在 v3-admin-vite 项目中整合 Pont 接口生成工具的全过程。内容涵盖 Pont 引擎的安装配置、代码生成路径调整、Prettier 格式统一，以及解决 Pont 默认 POST 请求参数过长问题的关键步骤。通过修改模板文件并适配 v3-admin 的 service.ts，实现了表单编码与 JSON 数据的灵活切换，最终完成前后端接口的高效一体化开发。

需求

当前后端 Admin 模板采用 v3-admin-vite，为了实现前后端统一的一体化开发流程，需要引入并整合 Pont 接口生成工具。

安装PONT

依据官方文档完成 Pont Engine 的安装，随后在项目根目录执行 `pont start` 命令。需要注意的是，由于 v3-admin-vite 将源代码存放于 `src` 目录下，因此必须调整生成代码的目标路径以匹配项目结构。

数据源指向 Swagger 的 API 地址，具体的 Swagger 配置过程此处省略。接下来，在 VSCode 中安装 Pont 插件以便生成 JavaScript/TypeScript API 代码。在生成代码之前，建议对配置文件进行适当修改。

格式统一化

若直接生成代码，由于 Prettier 格式化规则的影响，可能会产生大量代码错误提示。解决方法是参考项目根目录下 `v3-admin-vite` 的 `prettier.config.js` 配置，同步修改根目录下的 `pont-config.json`，确保两者的格式化规则保持一致。

随后在 VSCode 中切换至 Pont 面板，点击按钮拉取远程数据源并生成接口代码：

此时代码生成完毕，生成的代码与接口之间的对应关系如下：

每个导出的方法对应一个独立的 TypeScript 文件。

整合请求

前序步骤完成后，v3-admin 原有的请求逻辑与 Pont 生成的代码仍各自独立运行。为了实现无缝衔接，需要将两者进行整合。

v3-admin 原有的请求逻辑封装在 `src/util/services.ts` 文件中。

Pont 生成的基础请求逻辑位于 `src/services/pontCore.ts`。

需要修改 `pontCore.ts` 以适配 v3-admin 的请求规范。尽管大部分情况下 Pont 与 ccframe 的状态码兼容，但仍存在几个关键问题需要解决。

1）请求长度问题：Pont 默认配置下，POST 请求会将所有参数拼接至 URL 中，见相关代码片段。

该逻辑主要执行两项操作：

1）将路径中的占位符（如 `{id}`）替换为 `param` 中对应的值，并从 `param` 对象中移除该属性。

2）将 `param` 中剩余的参数附加到 URL 查询字符串后。

因此，当 POST 请求参数过长时，这种拼接方式会导致 URL 超出浏览器或服务器的承载长度限制，不适合传输大量数据。为此，需要扩展表单发送方式，使 POST 请求采用表单编码格式进行传输。

遵循最小修改原则，我们只需修改 `pontTemplate.ts`，不再直接使用 `PontCore`，而是复用 v3-admin 的请求逻辑：

import { Interface, BaseClass, Property, CodeGenerator, Surrounding } from 'pont-engine'
export default class MyGenerator extends CodeGenerator {
  getInterfaceContentInDeclaration(inter: Interface) {
    const requestParams = inter.getRequestParams()
    const paramsCode = inter.getParamsCode('Params')
    return `
      export ${paramsCode}
      export type Response = ${inter.responseType}
      export const init: Response;
      export function request(${requestParams}): Promise<Response>;
    `
  }
  getBaseClassInDeclaration(base: BaseClass) {
    const originProps = base.properties
    base.properties = base.properties.map((prop) => {
      return new Property({
        ...prop,
        required: false
      })
    })
    const result = super.getBaseClassInDeclaration(base)
    base.properties = originProps
    return result
  }
  getInterfaceContent(inter: Interface) {
    //const method = inter.method.toUpperCase()
    const axiosParamKey = 'GET' == inter.method.toUpperCase() ? 'params' : 'data' // 如果是GET，放param，如果是POST/PUT，放data
    const requestParams = inter.getRequestParams(this.surrounding)
    const paramsCode = inter.getParamsCode('Params', this.surrounding)
    return `
    /**
     * @desc ${inter.description}
     */
    import * as defs from '../../baseClass';
    import { request as service } from '../../../utils/service';
    export ${paramsCode}
    export const init = ${inter.response.getInitialValue()};
    export function request(${requestParams}, jsonPost: boolean = false) {
      return service({url:"${inter.path}", ...${inter.getRequestContent()}, ${axiosParamKey}: params, jsonPost})
    }
   `
  }
}

进行测试验证：

import './../../services/'
API.commonAdmin.doLogin
  .request({ loginId: 'admin', userPsw: 'ssss', sid: '8888', validateCode: 'nere' })
  .then((res) => {
    console.log('*****', res)
  })

可以看到请求已成功输出。但系统报错找不到参数，原因是请求被编码为 `application/json` 格式，而服务端未使用 `@RequestBody` 接收，导致无法解析。鉴于大多数请求为 form 格式的 key-value 数据，较少涉及结构化数据，因此默认编码应设为 `application/x-www-form-urlencoded`。同时，为了支持少量结构化数据，需在模板中添加一个 `jsonPost` 变量：当该变量开启时，采用 `application/json` 编码。修改 `src/utils/service.ts` 的请求部分如下：

/** 扩展了jsonPost参数 */
export interface AxiosRequestConfigEx extends AxiosRequestConfig {
  jsonPost?: boolean
}
/** 创建请求方法 */
function createRequest(service: AxiosInstance) {
  return function <T>(config: AxiosRequestConfigEx): Promise<T> {
    const token = getToken()
    const defaultConfig = {
      headers: {
        // 携带 Token
        Authorization: token ? `Bearer ${token}` : undefined,
        'Content-Type': 'application/x-www-form-urlencoded' //默认form编码，少量超大对象使用jsonPost
      },
      timeout: 10000, //默认10秒请求超时
      baseURL: import.meta.env.VITE_BASE_API,
      data: {}
    }
    // 将默认配置 defaultConfig 和传入的自定义配置 config 进行合并成为 mergeConfig
    const mergeConfig = merge(defaultConfig, config)
    if (config.jsonPost == true) {
      mergeConfig.headers['content-type'] = 'application/json'
    }
    return service(mergeConfig)
  }
}

配合模板中传入的 `jsonPost` 变量，当 `jsonPost` 传值为 `true` 时，即可通过 JSON Body 传递数据。