3. 参数类型与结构：基本类型参数（字符串、数字、布尔）、复合类型参数（列表、字典）、参数结构设计（扁平 vs 嵌套）

说实话，参数类型这块，很多人一开始觉得没什么好讲的。不就是字符串、数字、布尔嘛，谁不会用？但我在实际项目中踩过不少坑，才意识到——参数类型选不对，后面优化起来真要命。

咱们先看一个最简单的场景：你要批量发送消息，每条消息里带一个用户名。这个用户名，是字符串。那数字呢？比如用户ID、订单金额。布尔呢？比如是否VIP、是否已支付。这些基本类型，看起来简单，但组合起来就复杂了。

3.1 基本类型参数：字符串、数字、布尔

先说说字符串。我个人习惯，所有文本类参数统一用字符串。但要注意编码问题。我记得有一次，项目里传了一个带emoji的用户名，结果服务端解析乱码了。嗯，从那以后，我所有字符串参数都强制要求UTF-8编码。

数字参数呢？我建议整数用int，浮点数用float。但有个坑——金额计算。如果你用float存金额，0.1+0.2可能不等于0.3。我在一个支付项目里遇到过这个问题，后来全部改用整数，以分为单位存储。

// 推荐：整数存储金额（单位：分）
{
  "amount": 1999,  // 实际19.99元
  "currency": "CNY"
}

// 不推荐：浮点数存储金额
{
  "amount": 19.99,  // 可能精度丢失
  "currency": "CNY"
}

布尔参数更简单，但要注意命名规范。我习惯用is开头，比如isVip、isPaid。别用flag、status这种模糊的词，你想想看，别人看代码时根本不知道true代表什么。

基本类型	推荐命名	常见坑点
字符串	userName, messageContent	编码问题、特殊字符转义
数字	userId, orderAmount	浮点精度、整数溢出
布尔	isVip, isActive	命名模糊、类型混用

3.2 复合类型参数：列表、字典

基本类型搞定了，但实际业务中，参数往往是复合的。比如你要批量发送消息，收件人列表就是一个数组。每个收件人可能有多个属性，那就得用字典。

列表（数组）参数，我建议保持元素类型一致。别一个数组里既有字符串又有数字，解析起来很麻烦。我在一个项目中见过这种写法，后来重构时改得想哭。

字典（对象）参数，要注意键的命名规范。我习惯用驼峰命名法，比如firstName、lastName。别用下划线，也别用中文键名。你想想看，如果键名是中文，跨语言调用时编码问题会让你崩溃。

// 推荐：复合参数结构
{
  "batchId": "B20240301",
  "recipients": [
    {
      "userId": 1001,
      "userName": "张三",
      "isVip": true
    },
    {
      "userId": 1002,
      "userName": "李四",
      "isVip": false
    }
  ],
  "messageTemplate": "您好，{userName}，您的订单已发货。"
}

这里要注意，复合类型参数的嵌套层级不要太多。我见过一个参数，嵌套了5层，解析时性能很差，而且调试起来特别痛苦。一般来说，嵌套不超过3层比较合理。

3.3 参数结构设计：扁平 vs 嵌套

说到参数结构，就不得不提扁平化和嵌套化之争。我个人更倾向于扁平化，除非业务逻辑确实需要嵌套。

扁平化的好处很明显：解析快、调试方便、文档清晰。你想想看，一个扁平的JSON，一眼就能看出所有字段。嵌套的呢？你得一层层展开，才能找到想要的字段。

但嵌套也不是一无是处。比如你要表达“用户的地址信息”，用嵌套就很自然：

// 嵌套结构：适合表达层级关系
{
  "userId": 1001,
  "address": {
    "province": "广东省",
    "city": "深圳市",
    "district": "南山区",
    "detail": "科技园南区A栋"
  }
}

// 扁平结构：适合快速解析
{
  "userId": 1001,
  "addrProvince": "广东省",
  "addrCity": "深圳市",
  "addrDistrict": "南山区",
  "addrDetail": "科技园南区A栋"
}

那什么时候用扁平，什么时候用嵌套？我总结了一个简单的判断标准：

• 字段独立性强：用扁平。比如用户基本信息，每个字段都是独立的。
• 字段有明确的父子关系：用嵌套。比如地址、配置项。
• 字段数量超过10个：考虑分组嵌套。但嵌套层级不超过3层。
• 需要频繁增删字段：用扁平。嵌套结构改起来成本高。

下面这张图，是我在实际项目中总结的参数结构设计决策流程：

最后说一个实战经验。我在做批量发送系统时，参数结构设计遵循一个原则：接口参数要自解释。什么意思？就是别人看到你的参数名，不用看文档就能猜出大概意思。比如createTime比ct好，isActive比flag好。