第2章 初始化参数基础：常见参数类型
聊初始化参数，绕不开一个基本问题——参数到底长什么样？说白了，你传给 SDK 的每个配置项，背后都有个确定的类型。类型错了，轻则功能不生效，重则直接崩溃。我见过不少团队为这个踩坑，所以咱们先把地基打牢。
2.1 参数类型为什么重要？
你想想看，SDK 拿到参数后，会用特定的方式去解析。字符串就按文本处理，数字就做算术运算，布尔值就走分支判断。我在项目中遇到过几次「传了正确的值但 SDK 没反应」的案例，最后定位发现是类型不匹配——比如应该传数字的传成了字符串，SDK 内部做了松散比较才没出大错，但性能白白损耗了。
2.2 六种常见参数类型
我根据实战经验，把最常见参数类型整理成了一张表。这些类型几乎覆盖了 95% 的 SDK 初始化场景。
| 类型 | 示例值 | 典型用途 | 容易踩的坑 |
|---|---|---|---|
| 字符串 (string) | "prod", "https://api.example.com" |
环境标识、API 地址、语言代码 | 忘了转义或截断 |
| 整数 (int) | 5000, 3 |
超时毫秒数、重试次数、线程数 | 负数或超出范围 |
| 布尔值 (bool) | true, false |
开关控制：是否启用日志、是否自动连接 | 传了 0/1 但 SDK 只认 `true/false` |
| 浮点数 (float/double) | 0.8, 3.14 |
采样率、比例、阈值 | 精度丢失或 NaN |
| 数组/列表 (array/list) | ["tag1", "tag2"] |
白名单、黑名单、支持的区域列表 | 元素类型不统一 |
| 字典/对象 (object/map) | { "key": "value" } |
自定义扩展配置、元数据 | 嵌套过深导致解析失败 |
2.3 字符串参数：双刃剑
字符串最灵活，也最容易出问题。我个人的习惯是：能用枚举就别传字符串。比如环境参数：
// ❌ 不推荐：拼写错误直接失效
init({ env: "prd" }) // "prod" 写成 "prd"，SDK 默认走开发环境
// ✅ 推荐：用常量或枚举约束
const ENV = { PROD: "prod", DEV: "dev" };
init({ env: ENV.PROD })
还有一个坑——字符串长度。我记得有一次合作伙伴传了个 10KB 的字符串给 SDK 当 `userAgent`，结果每次初始化都要多花 200ms 做序列化。嗯，这里要注意，SDK 内部可能对字符串有长度限制，超过会被截断或报错。
2.4 整数参数：小心边界
整数看似简单，实际坑位不少。我给你三个最常见的：
- 范围越界——比如 timeout 传了 -1，SDK 可能理解成「无限等待」或者直接报错。我建议设置时至少做一次合法性判断。
- 单位混淆——有的 SDK 用毫秒，有的用秒。我曾经把「5 秒」写成了 5 毫秒，结果连接总是超时，排查了半天才发现。
- 0 的特殊含义——很多 SDK 把 0 当成「不限制」甚至「禁用」。传 0 之前一定要查文档。
// 典型示例：合理的超时参数校验
if (timeout < 1000) {
console.warn("timeout 至少 1000ms，已自动修正");
timeout = 1000;
}
init({ connectionTimeout: timeout });
2.5 布尔参数：最容易被低估
布尔参数，只有 true 和 false 两个值，但很多人会想当然。你想想看，SDK 内部判断方法千奇百怪：
- 有些用
if (param === true)—— 严格判断 - 有些用
if (param)—— 宽松判断，0 和 "" 都被当成 false - 还有些用
if (param !== false)—— 只要不传 false 都算 true
所以，如果你想关闭某个功能，最安全的做法是显式传 false，别依赖默认值。
2.6 浮点数与精度问题
浮点数在文案里看起来没什么，但计算机内部用二进制表示，0.1 + 0.2 不等于 0.3 这个老梗我就不重复了。我特别想说一下「采样率」这种参数：
// 采样率 0.8 代表 80% 的数据上报
init({ sampleRate: 0.8 });
// 如果 SDK 内部用浮点数比较，别传 80 或 "80%"
// 也别传 0.8000000000000001
很多人把整数和浮点数搞混。比如传 5 当浮点数可能没问题，但传 0.8 当整数就会被截断成 0。我的建议是：看 SDK 文档的类型定义，按类型传，别凭感觉。
2.7 数组与字典：结构决定性能
数组和字典参数通常用于传递更复杂的配置。这类参数有两个关键点：
- 不要传可变引用——如果你在初始化后继续修改数组，SDK 内部可能持有同一个引用，导致行为不可预期。我习惯用浅拷贝传进去：
init({ tags: [...myTags] })。 - 控制元素数量——一个数组传了 10000 个元素，SDK 每次初始化都要遍历一遍，直接影响启动速度。如果必传大量数据，考虑用分页或懒加载。
2.8 本章知识体系总览
下面这张图把常见参数类型、核心要点和常见坑位串在了一起。建议你存下来，以后调参数时对照着看。
2.9 实战检查清单
每次对接新 SDK 初始化参数时，我都会按下面几步过一遍。你也可以把它当成一个 checklist：
- 读文档——确认每个参数的类型定义，别靠猜。
- 做类型校验——在初始化前加一层校验，类型不对直接抛提示，别让错误扩散。
- 测试边界值——比如超时传 0、传负数、传极大的数，看 SDK 是否优雅处理。
- 检查默认值——你不传这个参数时，SDK 会用什么？是否符合预期？
- 看源码（如果有）——我习惯翻一下 SDK 的初始化函数，确认它对各类型的处理方式，避免文档滞后。
这一章把参数类型的基本盘讲透了。从下一部分开始，我们会深入具体场景——怎么根据业务需求选择参数值，怎么在性能和功能之间做取舍。嗯，那些才是真正的调优功夫。