如何开发 Whistle 插件，基本目录和入口逻辑怎么设计？

开发 Whistle 插件时，先别急着写复杂的拦截逻辑。一个好插件至少要回答三件事：它提供什么协议或规则能力，配置从哪里来，出错时怎样不影响正常代理。插件适合做团队可复用的能力，比如统一鉴权头、动态 mock、请求审计、环境面板；如果只是临时改一个接口，用普通 rules 和 values 更轻。

插件项目应该长什么样？

Whistle 插件本质上是一个 npm 包，包名通常使用 whistle.xxx 或团队约定的插件名。最小结构包括 package.json、入口文件、可选的 rules、values、README。入口文件负责注册服务逻辑，配置文件负责描述插件名称、菜单、规则等元信息。

bash
mkdir whistle.demo-helper
cd whistle.demo-helper
npm init -y
mkdir lib test
touch index.js README.md

json
{
  "name": "whistle.demo-helper",
  "version": "0.1.0",
  "main": "index.js",
  "whistleConfig": {
    "name": "demo-helper",
    "description": "team debug helper"
  }
}

入口逻辑怎么写？

插件入口不要把所有事情都塞进一个巨大函数。建议把路由、配置读取、数据生成、错误处理拆开，入口只做组装。请求处理时要注意异步错误，任何未捕获异常都可能让调试体验变得很差。

javascript
module.exports = function(server, options) {
  server.get('/cgi-bin/ping', function(req, res) {
    res.json({ ok: true, name: 'demo-helper' });
  });

  server.on('request', function(req) {
    req.headers['x-debug-from'] = 'whistle-plugin';
  });
};

这个例子只演示结构，真实项目里还应该把 header 名称、开关和目标域名做成配置，而不是写死。插件越通用，越要减少默认侵入性，让使用者通过规则明确启用。

在规则里如何启用插件？

安装本地插件可以用 npm link 或 Whistle 的安装命令。这里要先约定插件名称和规则写法，否则同一个插件在不同同学机器上可能出现“装了但没命中”的情况。建议 README 里放一条最小可验证规则，再配一个 /cgi-bin/ping 检查入口，避免把安装问题误判成业务代理问题。调试阶段推荐本地链接，发给团队使用前再发布到私有 npm 或写清楚安装方式。规则里通过 plugin:// 或插件提供的协议启用，具体取决于插件能力设计。

bash
npm link
w2 install demo-helper
w2 restart

text
# 只对指定接口启用插件，避免全局污染
api.example.com/api/order plugin://demo-helper

插件里常见能力怎么拆？

如果是动态 mock，建议把数据模板、参数解析、延迟和错误比例拆成独立模块。目录上可以保留 lib/mock、lib/config、lib/routes 这类清晰边界，让入口文件只负责装配。这样后续增加新接口时，不会把所有逻辑都堆进 index.js。如果是请求审计，建议只记录必要字段，例如 URL、方法、状态码、耗时，不要默认落敏感 header 和 body。如果是团队面板，可以提供 /cgi-bin/* 接口给前端页面读取配置，但要避免无鉴权暴露内部信息。

追问

什么时候该写插件，什么时候只写规则？

一次性的 host、mock、header 修改用规则更合适，写插件反而增加维护成本。取舍在于插件能复用、可封装复杂逻辑，但发布、版本和兼容性都要有人负责。边界可以这样定：需要参数化、多人复用、包含 UI 或复杂状态时再考虑插件。踩坑是为了一个临时接口写插件，最后没人维护，Whistle 升级后还会拖累团队环境。

插件默认要不要全局生效？

通常不要，默认全局生效很容易误伤无关请求。取舍是全局生效配置简单，但排查问题时很难判断某个 header 或响应是不是插件改的。边界是审计、日志类插件可以全局观察，但修改请求或响应的逻辑最好通过规则显式启用。踩坑是插件给所有请求加了测试 header，结果第三方接口因为非法 header 拒绝访问。

插件配置应该放在哪里？

稳定默认值可以放 package.json 或代码常量，团队可变配置建议放 rules、values 或单独配置文件。取舍是代码内置最可靠，但每次调整都要发版；外部配置灵活，但需要校验和文档。边界是密钥、token、生产 Cookie 不应该进入插件包。踩坑是插件读取不到配置时静默使用默认生产域名，调试请求被转到了错误环境。

插件如何处理错误才安全？

插件内部要捕获异步错误，并给出可观察的日志或降级响应。取舍是直接抛错能尽快暴露问题，但会影响代理链路；降级更稳，但不能把错误吞得毫无痕迹。边界是 mock 类插件可以返回明确错误，审计类插件失败时应尽量不阻塞原请求。踩坑是读文件、查数据库这类操作用同步阻塞方式写在请求路径里，流量一大 Whistle 控制台也会变卡。

本地插件怎么给团队使用？

开发阶段用 npm link 最快，团队使用建议发布到私有 npm，并固定版本号。取舍是本地链接便于调试，但每个人机器状态不同；包管理方式更稳定，但需要发版流程。边界是不要让团队依赖某个同学电脑上的本地路径。踩坑是 README 只写了安装命令，没有写规则示例和验证方法，新同学装完也不知道插件是否生效。