GET vs POST 请求参数处理指南

📋 概述

生成器能够正确区分和处理 GET 和 POST 请求的不同参数类型。

🔍 参数类型说明

1. GET 请求参数

参数位置: URL 查询字符串（Query Parameters）

OpenAPI 定义:

paths:
  /srv/:
    get:
      parameters:
        - name: page
          in: query          # ✅ GET 请求使用 query
          description: 页码
          schema:
            type: integer
        - name: pageSize
          in: query          # ✅ GET 请求使用 query
          description: 每页数量
          schema:
            type: integer
        - name: a
          in: query          # ✅ action 也在 query 中
          example: user_info
          schema:
            type: string

生成的代码:

/**
 * @param {Object} params 请求参数
 * @param {integer} params.page (可选) 页码
 * @param {integer} params.pageSize (可选) 每页数量
 */
export const getUserInfoAPI = (params) => fn(fetch.get(Api.GetUserInfo, params));

2. POST 请求参数

参数位置: 请求体（Request Body）

OpenAPI 定义:

paths:
  /srv/:
    post:
      parameters:
        - name: user-id
          in: header         # ⚠️ Header 参数（不显示在 JSDoc 中）
          schema:
            type: string
        - name: user-token
          in: header         # ⚠️ Header 参数（不显示在 JSDoc 中）
          schema:
            type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                a:
                  example: user_edit    # ✅ action 在 requestBody 中
                  type: string
                name:
                  description: 姓名
                  type: string
                avatar:
                  description: 头像
                  type: string

生成的代码:

/**
 * @param {Object} params 请求参数
 * @param {string} params.name (可选) 姓名
 * @param {string} params.avatar (可选) 头像
 */
export const editUserInfoAPI = (params) => fn(fetch.post(Api.EditUserInfo, params));

🎯 关键区别

特性	GET 请求	POST 请求
参数位置	URL 查询字符串	请求体
参数定义	parameters + in: query	requestBody
Action 位置	parameters 中	requestBody 中
生成方法	fetch.get()	fetch.post()
Header 参数	显示在 JSDoc 中	❌ 不显示（自动过滤）

📝 参数过滤规则

自动过滤的参数

以下参数不会出现在生成的 JSDoc 中：

1. a 参数 - action 参数，已在 URL 中
2. f 参数 - 业务模块标识，已在 URL 中
3. Header 参数 - in: header 的参数

原因: 这些参数由框架或请求拦截器自动处理，开发者无需手动传递。

示例

OpenAPI 定义:

parameters:
  - name: a
    in: query
    example: user_info     # ❌ 不会显示在 JSDoc 中

  - name: f
    in: query
    example: behalo         # ❌ 不会显示在 JSDoc 中

  - name: user-id
    in: header              # ❌ 不会显示在 JSDoc 中

  - name: page
    in: query
    example: 1              # ✅ 会显示在 JSDoc 中

生成的 JSDoc:

/**
 * @param {integer} params.page (可选) 页码  # ✅ 只显示业务参数
 */

🔧 使用示例

GET 请求示例

// 调用 GET 接口
const result = await getUserInfoAPI({
  page: 1,
  pageSize: 10
});

// 等价于
// GET /srv/?a=user_info&page=1&pageSize=10

POST 请求示例

// 调用 POST 接口
const result = await editUserInfoAPI({
  name: '张三',
  avatar: 'https://...',
  mobile: '13800138000'
});

// 等价于
// POST /srv/?a=user_edit
// Content-Type: application/x-www-form-urlencoded
// Body: name=张三&avatar=https://...&mobile=13800138000

📊 完整对比

GET 请求 - 获取订单列表

OpenAPI:

get:
  parameters:
    - name: a
      in: query
      example: order_list
    - name: page
      in: query
      type: integer
      description: 页码
    - name: pageSize
      in: query
      type: integer
      description: 每页数量

生成代码:

const GetList: '/srv/?a=order_list'

/**
 * @description: 获取订单列表
 * @param {Object} params 请求参数
 * @param {integer} params.page (可选) 页码
 * @param {integer} params.pageSize (可选) 每页数量
 */
export const getListAPI = (params) => fn(fetch.get(Api.GetList, params));

POST 请求 - 修改用户信息

OpenAPI:

post:
  parameters:
    - name: user-id
      in: header
    - name: user-token
      in: header
  requestBody:
    content:
      application/x-www-form-urlencoded:
        schema:
          properties:
            a:
              example: user_edit
            name:
              type: string
              description: 姓名

生成代码:

const EditUserInfo: '/srv/?a=user_edit'

/**
 * @description: 修改我的信息
 * @param {Object} params 请求参数
 * @param {string} params.name (可选) 姓名
 */
export const editUserInfoAPI = (params) => fn(fetch.post(Api.EditUserInfo, params));

✅ 最佳实践

1. GET 请求定义

get:
  parameters:
    - name: a
      in: query
      example: your_action    # ✅ action 在 query 中

    - name: your_param
      in: query               # ✅ 业务参数也用 query
      description: 参数描述
      schema:
        type: string

2. POST 请求定义

post:
  parameters:
    - name: auth-header
      in: header              # ✅ 认证信息放 header

  requestBody:
    content:
      application/x-www-form-urlencoded:  # 或 application/json
        schema:
          properties:
            a:
              example: your_action  # ✅ action 在 body 中
            field1:
              type: string
              description: 字段描述

3. 避免混淆

❌ 不要这样定义：

post:
  parameters:
    - name: data_field
      in: query               # ❌ POST 不要用 query 传数据

✅ 应该这样定义：

post:
  requestBody:
    content:
      application/json:
        schema:
          properties:
            data_field:       # ✅ POST 数据放 requestBody
              type: string

🎯 总结

• GET 请求: 参数在 parameters + in: query
• POST 请求: 参数在 requestBody 中
• Header 参数: 自动过滤，不显示在 JSDoc
• Action 参数: 自动提取并添加到 URL 中

这样可以确保生成的代码简洁、易用，符合实际开发习惯！