1. 搜出来的“harness-sdk”有很多，先分清你在找哪一个
如果你在搜 "harness-sdk"，大概率已经被 Harness 平台里的某个提示带过来。我第一次搜索这个词，是在一个灰度发布需求里：产品要按用户百分比放新功能，又要在出问题时秒级关闭。传统做法是改代码、发版本，一来一回少说半小时。Harness 这种特性开关平台把控制权挪到了远程配置，而 SDK 就是业务代码里接这把开关的把手。第一次搜下来我发现，GitHub 和 npm、PyPI、Maven 上叫 harness-sdk 或名字里带 harness 的包不少，指向的东西大概分成三类：一类是 Harness Feature Flags 的服务端 SDK，用来在运行时读取功能开关；一类是封装 Harness REST API 的客户端，用来做流水线、基础设施的自动化；还有一类是社区或个人维护的集成库，封装深度和文档质量参差不齐。我当时的需求是运行时开关，所以本文会重点讲 Feature Flags SDK 这条线，同时会提一下怎么避免把这三类混为一谈。
1.1 我为什么没有选“REST API 直连”
其实拍板之前我犹豫了一下：只是读一个开关值，直接用 REST API 调 Harness 不就行了吗？为什么还要多装一个 SDK？后来实测下来，SDK 的存在不是增加依赖，而是解决 REST API 解决不好的三类问题：第一是缓存，SDK 启动时会拉一整套 Flag，业务进程本地就有状态，不需要每次请求都远程往返；第二是变更感知，它背后是一条长连接，控制台改 Flag 后能快速同步到本地缓存，REST 轮询只能掐着间隔做；第三是默认值和降级，网络抖动时 SDK 可以回落到你给好的默认值，同时保留重试机制。相当于你自己去餐厅每次现点菜，和会员餐厅把今日菜单推给你、还告诉你哪个菜暂停供应之间的区别。虽然 REST API 也能写，但要自己处理连接、缓存和重试，这部分成本会随着接入 Flag 数量增加迅速膨胀。
1.2 顺带分清 Server SDK 与 Client SDK
Harness Feature Flags 的 SDK 还分服务端和客户端两类。初看名字容易晕：Server SDK 跑在你的后端进程里，拥有完整评估能力，也是本文示例用的；Client SDK 跑在 App 或 Web 端，因为不能把 SDK Key 暴露在客户端，往往要走网关或受限模式。如果你的场景是 Android、iOS、Flutter、Web，集成逻辑跟后端完全不同，网上搜 "harness-sdk" 时最好在材料里看清楚 target 是 Server 还是 Client。我在第一次选型时把 Server SDK 的初始化代码搬进了一个前端页面，怎么都鉴权失败，后面才意识到拿错了类别。另外，不同语言的服务端 SDK 命名习惯也不一样，Node.js 里可能叫 @harnessio/ff-nodejs-server-sdk，Python 里可能叫 harness-featureflags，Go、Java 也各有对应，搜包的时候要按官方文档的链接走，不要只靠关键词盲搜。
1.3 这个标题下另一条线：Harness API SDK
如果你的需求不是功能开关，而是想在流水线、基础设施自动化里调用 Harness 的 API，那你搜到的 harness-sdk 可能是另一类封装。这类 SDK 主要帮你完成创建 Pipeline、查询部署状态、触发工作流之类的操作，面对的鉴权体系是 API Key 和 JWT，与 Feature Flags 的 SDK Key 完全不同。我建议你在动手前先想清楚自己到底要哪一条线：业务代码里读 Flag 选 Feature Flags SDK；运维平台自动化选 Harness API 客户端。两者如果混着看，容易把初始化参数和鉴权方式都搞错，后面排查起来非常痛苦。这篇主要走业务代码集成这条路线，API 自动化只在这里给个方向，细节不再展开。
2. 环境准备：创建 Flag、拿 SDK Key、确认网络可达
2.1 在控制台创建一个可用的 Feature Flag
这一步其实不难，但顺序错了会绕路。进入 Harness 后先创建一个项目，然后在项目下进入 Feature Flags 模块。创建 Flag 时，类型通常选 Boolean，名字和标识符要提前想好，因为代码里引用的是 Identifier 而不是展示名。如果你以后要做多变量配置，也可以选 String 或 Number 类型，但第一支 Flag 建议用 Boolean 把链路跑通。创建完还要绑定环境，Harness 里的环境就是开发、测试、生产这类隔离空间，同一个 Flag 在不同环境可以有不同的状态。这一步的坑在于：很多人创建时忘了选环境，后面本地调试时读到的始终是默认环境的值，误以为自己没连上。
2.2 SDK Key 的正确获取方式
SDK Key 是环境级别的，一般在 Environments 入口里，选择目标环境后能看到 SDK Keys。点击新建会得到一串带环境标识的 key。这里最关键的一点是：Feature Flags SDK 用的不是 Harness API Key，不要把控制台右上角个人 API Key 硬塞进来。两项东西的鉴权体系和用途完全不同。其次，服务端代码要选择 Server SDK Key，不要拿 Client SDK Key 放到后端，因为 Client Key 在设计上不具备服务端评估权限。我当时踩的第一个坑就出现在这里，详见后面踩坑章节。拿到 Key 后，建议配置到环境变量，不要硬编码在代码里，更不要提交进 Git 仓库。如果你的团队有多个环境，我建议从一开始就在环境变量层面把 dev、staging、prod 的 SDK Key 分开，避免后面切环境时改代码。
2.3 网络连通性：先让一条最简单的命令打通
SDK 初始化时要访问 Harness 官方 Endpoint，如果你的服务在私有网络或容器集群里，要先确认网络策略允许访问目标域名和对应端口。官方文档会有 Endpoint 的配置项，比如给 SaaS 用户的和给自建实例的自定义地址是不同的。最简单的验证方式是，在启动代码前先用 curl 探测几次，能正常返回 HTTP 层响应再继续。这一步很多人跳过，结果初始化时一直超时，又找不出是代码原因还是网络原因。另外，如果你在企业内网部署，SDK 是否要配置特定网络出口请以安全合规要求为准，不要为了连通性私下绕过网络策略，这是基本红线。网络问题排查顺序建议是：域名解析、端口连通、HTTP 状态码、SDK 初始化日志，逐层确认。
2.4 初始化参数里最容易被忽略的 target
初始化 Feature Flags SDK 时，绝大多数示例代码都会要求传一个 target。target 最少要有 identifier，它代表“这次评估是替哪个用户、哪一个实体去取开关值”。如果所有请求都用同一个 identifier，那么 Flag 的百分比灰度、用户组规则全部失效，因为系统会认为始终是同一个人在访问。建议在服务端用一个能从请求中提取的不变 ID，比如用户 ID、设备 ID；没有登录态的匿名接口也要生成一个生命周期内的匿名 ID。target 还可以塞 attrs，用于做更细的匹配规则，这个后面进阶部分会用到。
重要提示：target.identifier 不是你随意填的调试字段，它直接影响百分比灰度和用户维度规则的准确性。生产环境里同一个用户每次请求都要固定传同一个 ID。
3. 核心集成链路：初始化、取值、缓存与降级
3.1 SDK 到底是怎么拿到 Flag 值的
大多数服务端 SDK 的工作方式是：初始化时建立长连接，拉取一次全量开关状态到本地内存；之后 Harness 控制台有任何变更，服务端会通过流式推送更新本地。也就是说，你每次调用 evaluate 系列方法，其实是在读本地缓存，几乎不消耗网络 RTT。这个设计是 Feature Flag SDK 和普通 HTTP 客户端最大的区别。理解这一点后，你会明白为什么官方文档总说“不用每次调用都初始化”。如果你在一个高频路径上每次请求都新建 Client，不仅浪费连接，还会让本地缓存永远建立不起来，Flag 变更也永远无法同步。
3.2 最小可用代码：以 Node.js 服务端为例
我这里用 Node.js 服务端 SDK 举个完整的例子，不同语言的 API 名字会略有差异，但思路一致。假设你已经把 HARNESS_SDK_KEY 配到了环境变量里：
const { initialize } = require('@harnessio/ff-nodejs-server-sdk'); async function start() { const client = initialize({ apiKey: process.env.HARNESS_SDK_KEY, target: { identifier: 'server-bootstrap' }, }); // 等待 SDK 完成第一次同步，避免启动后第一个请求拿到默认值 await client.waitForInitialization(); console.log('Harness SDK ready'); return client; }然后在请求处理函数里取值：
const enabled = await client.boolVariation('your_flag_identifier', false); if (enabled) { // 新逻辑 } else { // 旧逻辑 }代码里第二个参数 false 就是默认值，网络不可用或者 Flag 不存在时返回它。有一点务必注意：不同版本的方法名可能从 boolVariation 改成 getBoolValue 之类，接入时以你锁定的官方版本文档为准。但参数顺序基本是“Flag 标识符 + 默认值”。如果你的项目用了 TypeScript，建议把 Flag Identifier 集中到一个常量文件里，避免在业务代码里到处散落字符串拼写错误。
3.3 优雅关停：别让后台连接拖住你的进程
SDK 在后台维持着流式连接，测试跑完如果不主动关闭，进程会一直挂住。很多同事抱怨“测试跑完不退出”，一问原因，基本是把 SDK 的 long-running connection 扔在那边没人管。建议在进程关闭时调用 client.close()；若是用 Jest 这类测试框架，在 afterAll 或 teardown 里关闭；若是服务器进程，在 SIGTERM 信号处理器里先关闭再退出。还有一个很隐蔽的点：如果你用的是 Serverless 函数，每次调用都初始化 SDK 会带来几十到几百毫秒的冷启动开销，需要把 client 放到全局复用，并且在处理函数结束后不能随意 close，否则下一个请求就失去缓存了。
3.4 默认值设置：比你想的要谨慎
每个 evaluate 调用都要给默认值，这个默认值不只是“没连上时的兜底”，更是发布初期的安全边界。我的习惯是：凡是控制风险型开关，默认值一律给 false 或关闭；凡是性能优化型开关，可以给 true 或流量小分支，但必须评审过。为什么这么谨慎？因为初始化失败、配置写错、网络被防火墙阻断，这三件事未必会抛异常——SDK 会在你的显式默认值上静默返回。如果你把新功能默认值写成了 true，等于在不可控状态下把流量切给了新逻辑。实践中我还会把默认值单独提出来，写成一个 getFlagOrDefault 方法，这样代码评审时一眼就能看到每个开关的兜底是什么。
4. 踩坑实录：我走过的四个典型弯路
4.1 把 SDK Key 当 API Key 用，鉴权一直 401
我第一次接入的时候，在控制台找了半天，看到个人设置里的 API Key 就复制了出来，填进 initialize。结果并不报错，但所有 evaluate 都异常，日志里有一串 401。排查过程是：先关了业务日志，打开 SDK 的 debug 日志，看到 response status 401；然后去对比控制台密钥类型，发现 Harness 的 API Key 用于管理 Rest API，而 Feature Flag 要的是环境页面里的 SDK Key。这两个 Key 长得都很像，不仔细看说明根本分不清。换掉之后问题消失。这个坑的核心教训是：鉴权信息不是“能通过控制台拿到就行”，必须对应模块和用途。
4.2 Flag 在控制台改了，业务侧等了一分钟才生效
有一段时间我在控制台把某个 Flag 从关到开，等了大几十秒，业务日志里仍然是关。查下来不是长连接断了，而是我把 Endpoint 配置成了自定义域名，但该域名背后的网关对流式连接支持不完整，SDK 检测到连接无法建立后自动回退成了轮询模式，轮询间隔默认较长。解决方法是使用官方推荐的 Endpoint，或者调小轮询间隔。这个案例说明：SDK 的“实时生效”是有前提的，长连接一旦没建立，实时性会退化成“准实时”。排查时可以打开 SDK 日志，看连接状态是 connected 还是 polling，能省很多时间。
4.3 多环境切换后读到“别人的开关值”
我们有 dev、staging、prod 三套环境，共用一个后端服务，环境变量切换时只改了数据库连接，没改 HARNESS_SDK_KEY。于是开发环境一直读生产环境的 Flag。更坑的是 Flag Identifier 一样，业务逻辑完全正常，就是值不对。后来我们在启动日志里显式打印当前 SDK Key 的前几位和环境标识，每次部署时先核对再放流量。如果你也有多环境复用代码库，建议把 SDK Key、环境标识、Flag 前缀都作为部署配置的一部分，而不是散落在代码仓库。
4.4 Serverless 场景下重复初始化的性能陷阱
我在一个云函数里把 SDK 初始化写在函数入口外还好，但团队里有同学写在处理函数内部，每个请求都 new 一次 client。结果就是每个请求平均多了几百毫秒延迟，而且 Flag 更新永远跟不上去。原因不难理解，SDK 每次初始化都要建连接、拉全量 Flag、开后台任务，这个成本在普通长驻进程里只付一次，在 Serverless 里如果写错位置就要付无数次。所以 Serverless 接入的时候，要把 client 声明在全局作用域，用懒初始化的方式复用；数据库连接池怎么复用，SDK Client 就怎么复用。
5. 进阶玩法：把 Feature Flags SDK 嵌进发布流程
5.1 自动化测试按开关分支跑两遍
功能开关带来的一个问题是，代码里有两套分支，你的自动化测试如果只测了默认路径，等于漏掉了一半逻辑。我们的做法是，在测试环境用环境变量把 Flag 预设成开和关，跑两遍全回归。之所以不用真正去控制台改，是因为测试的可重复性要求每次跑都从已知状态开始。SDK 在这里只负责帮你在被测代码里读取开关，而测试驱动层直接设置默认值即可。如果你的 SDK 支持本地覆盖模式，也可以用它把指定 Flag 锁死，这样回到代码逻辑里做分支覆盖会很快。
5.2 按用户百分比灰度时，target 必须传对
灰度发布里最常用的“给 10% 用户开新功能”，实际是在控制台把 Flag 的默认状态关掉，再加一条规则：target 的属性或 identifier 匹配某个百分比。这里 SDK 的作用是保证同一用户连续两次访问落到同一个结果区间。实现的关键是把 target.identifier 传对。我用过匿名 ID 之后发现，同一个浏览器每次请求都换 ID，灰度比例会失效，用户会一会儿在新逻辑一会儿在旧逻辑。要稳妥，就应该用登录用户 ID，或者生存期较长的设备 ID。这个细节不在 SDK 代码里，而在于你是否理解 Target 在整个评估模型中的位置。
5.3 功能稳定后，记得把开关拆掉
Feature Flag 用久了会产生“开关债”：判断语句到处都是，Flag 的控制台也堆满过期项。我的建议是每迭代结束做一次清理清单，凡是稳定运行超过两个版本的 Flag，先切到固定值观察一周，然后在代码里移除对应的 evaluate 和分支，最后去控制台归档。别小看这一步，欠债不还的 Flag 会让后续排查“某个行为怎么来的”变得极其困难。SDK 的依赖会因为你长期不清除而变大，默认值和分支逻辑越多，人脑负担就越重。我们在做清理时，会用一行注释标出每个 Flag 的上线时间和负责人，方便后续追溯。
6. 接入 Checklist：从零到生产环境一次过
如果你准备在团队里推进 harness-sdk，我建议按下面这个清单落地：
- 选定模块：Feature Flags 还是 API 自动化，别混；本文适用于前者。
- 创建项目与环境：Flag Identifier 和 Environment 提前规划，代码引用 Identifier。
- 区分 Key：Server 代码用 Server SDK Key，前端、移动端用 Client 方案，绝不把 API Key 塞给 SDK。
- 初始化一次：长驻进程启动时初始化一次并在 ready 后再服务流量；Serverless 则全局复用 client。
- 默认值保守：新功能默认 false，稳定后显式保留评估，不把安全边界交给运气。
- 记录上下文：每条 switch 日志至少记录 Flag Key、评估结果、Target ID，但不要放用户隐私字段。
- 清理开关：每两个迭代 review 一次存量 Flag，能移除就移除。
- 监控连接状态：部署后在日志里确认 connected，而不是 polling，否则实时变更会延迟。
这份清单不是从官方文档抄的，里面至少有三个是我差点线上事故换来的。你在接入时如果只记住一句话，我建议记住这句：SDK 并不神秘，它只是把远程开关变成你进程里一组可靠的本地状态，你真正要设计的，是状态变化之后业务怎么安全地向前走。如果后续有精力，还可以把 SDK 的指标接入到监控大盘，看看 Flag 评估耗时、默认值命中率、连接重连次数，这些数据能帮你更早发现集成问题，而不是等线上反馈。
