README_zh.md

Intercept Wave for IntelliJ IDEA

English | 简体中文

插件简介

Intercept Wave 是一款面向本地开发场景的 IntelliJ IDEA 插件，融合了类似 Nginx 和 Charles 的拦截、Mock 与代理能力。它可以拦截 HTTP 请求和 WebSocket（ws:// / wss://）消息，按需返回自定义 Mock 数据，或将流量桥接到上游服务获取真实响应。

✨ 多服务代理

• 📑 标签式界面：在独立标签页中管理多个代理配置组
• 🚀 多配置组：同时运行多个 Mock 服务，每个服务独立端口
• 🏗️ 微服务就绪：完美适配微服务架构（如用户服务 8888 端口，订单服务 8889 端口）
• 🔄 快速切换：通过标签页快速切换和管理不同的服务配置
• 🌍 多环境支持：轻松管理开发、测试、预发布等多个环境

核心能力

智能拦截与代理：

• 🎯 配置路径前缀（如 /api），精准命中指定请求
• 🧭 一个 HTTP 配置组内可配置多条路由规则，每条路由都拥有自己的前缀、目标地址、剥离前缀规则和 Mock 开关
• 🔁 支持类似 nginx 的路由本地路径重写，例如 /backend/users -> /v1/users
• 🔄 有 Mock 配置：返回预设的 Mock 数据，实现离线开发
• 🌐 无 Mock 配置：作为代理服务器，携带完整的 HTTP 请求头转发到原始服务器，获取真实数据
• 🔀 智能路径匹配：支持前缀去除，简化配置
• 📡 WebSocket Mock 与桥接：创建 WS 配置组，在本地开启 ws:// 监听，也可基于 PKCS#12 证书启用本地 wss://，并桥接到上游 ws:// / wss:// 服务，同时支持自动推送和手动推送消息

开发友好特性：

• 👥 目标用户：前端工程师、测试工程师、全栈开发者
• 🎨 可视化配置界面，需要时也可直接编辑项目配置文件
• 💾 配置持久化，项目级别隔离
• 🌐 自动处理 CORS 跨域问题
• ⏱️ 支持网络延迟模拟
• 🔧 自定义响应状态码和响应头
• 🍪 全局 Cookie 支持，轻松处理需要认证的接口

典型使用场景

1. 微服务开发：同时 Mock 多个微服务（用户服务、订单服务、支付服务等）
2. 前端独立开发：后端接口未就绪时，配置 Mock 数据继续开发
3. 接口测试：快速切换不同的返回数据，测试各种边界情况
4. 多环境调试：同时配置开发、测试、预发布等多个环境
5. 本地调试：部分接口使用 Mock，其他接口代理到测试服务器
6. 网络模拟：模拟慢速网络或接口超时场景
7. 跨域开发：自动添加 CORS 头，解决前端开发中的跨域问题

功能概述

Intercept Wave 提供以下核心功能：

• 接口拦截: 拦截特定接口并返回配置的 Mock 数据
• 代理转发: 自动转发未配置的接口到原始服务器
• WebSocket Mock 与推送: 启动本地 WebSocket Mock/代理服务，转发到上游 ws:///wss:// 端点，并可通过推送规则（周期/时间轴）或工具窗口手动推送消息。
• CORS 支持: 自动添加 CORS 头，解决跨域问题
• 请求保留: 保留原始请求头和 User-Agent
• 延迟模拟: 模拟网络延迟，测试慢速网络环境
• 状态码测试: 配置不同状态码测试错误处理逻辑
• 前缀过滤: 支持配置前缀过滤，简化接口访问路径
• 全局 Cookie: 配置全局 Cookie，支持需要认证的 Mock 接口

兼容性

Intercept Wave 支持基于 IntelliJ Platform 2023.1 及更新版本的 JetBrains IDE。插件以 2023.1 平台作为兼容基线构建，并输出 Java 17 字节码，以兼容 2023.x IDE 运行时。

插件验证矩阵覆盖以下产品的 2023.1 基线版本：CLion、DataGrip、DataSpell、GoLand、IntelliJ IDEA Community、IntelliJ IDEA Ultimate、PhpStorm、PyCharm Community、PyCharm Professional、Rider、RubyMine 和 WebStorm。

配置更新

• 配置 schema 会自动升级。现有旧配置可直接使用，保存时会自动写入当前 schema 版本（"version": "5.0"）。
• Mock JSON 自动规范化与最小化：支持单引号、注释、未加引号的键、尾逗号等宽松写法，保存时会自动压缩为紧凑 JSON；编辑时可使用“格式化 JSON”按钮美化显示。

安装

使用 IDE 内置插件系统

Settings/Preferences > Plugins > Marketplace > 搜索 "Intercept Wave" > Install

使用 JetBrains Marketplace

访问 JetBrains Marketplace 并点击 Install to ... 按钮安装。

或下载 最新版本 手动安装： Settings/Preferences > Plugins > ⚙️ > Install plugin from disk...

手动安装

从 GitHub Releases 下载最新版本，然后手动安装： Settings/Preferences > Plugins > ⚙️ > Install plugin from disk...

打包与发布说明（维护者）

• JetBrains Marketplace 和 IDE 手动安装都要求使用 ./gradlew buildPlugin 生成的原始插件压缩包。
• 始终上传 build/distributions/*.zip。
• 不要上传 build/libs/*.jar。
• 不要上传 ZIP 解压后的目录内容。
• CI 流程应直接保存并发布 ZIP 产物，不要先解压再二次打包。

发布前可在本地快速校验：

./gradlew buildPlugin
unzip -t build/distributions/*.zip

快速开始

1. 打开工具窗口

1. 在 IntelliJ IDEA 中打开项目
2. 点击左侧工具栏的 "Intercept Wave" 图标
3. 工具窗口会显示所有配置的代理组，以标签页形式展示

2. 管理配置组

工具窗口顶部提供全局操作：

• 启动所有: 启动所有已启用的配置组
• 停止所有: 停止所有运行中的服务
• 配置: 打开配置对话框，管理所有配置组

工具窗口标题栏还提供两个面向配置文件的快捷操作：

• 打开配置文件：直接在 IDE 编辑器中打开 .intercept-wave/config.json
• 重新加载配置：先保存 IDE 中尚未落盘的改动，再从磁盘重新加载配置并刷新工具窗口；只重启原本已经在运行的配置组

标签页说明

• 每个标签代表一个配置组（如"用户服务"、"订单服务"）
• 显示服务名称、端口号、启用状态
• 点击标签切换到对应的服务控制面板
• [+] 标签：点击快速打开配置对话框添加新配置组

单个服务控制

每个标签页面板显示：

• 配置状态: 显示该配置组是否启用
• 运行状态: 运行中 / 已停止
• 🔗 访问地址: 服务运行时的访问 URL
• 启动服务 / 停止服务: 控制单个服务的启停
• 当前配置:
  • HTTP 组现在使用路由树形卡片，子 Mock 项可直接快速编辑
  • WS 组现在使用规则卡片，并展示连接状态、发送入口和编辑入口

3. 配置代理组

点击 "配置" 按钮，打开配置对话框：

配置组管理（多标签页界面）

• 每个标签页代表一个配置组
• 标签显示格式：配置组名称 (:端口号)
• + 新增配置组: 添加新的配置组
• 删除当前配置组: 删除当前选中的配置组（至少保留一个）
• ← 左移 / 右移 →: 调整配置组的显示顺序

配置组设置

每个配置组包含以下设置：

基本配置：

• 协议类型: HTTP 或 WS。HTTP 组处理 HTTP 接口，WS 组处理 WebSocket 连接。
• 配置组名称: 自定义名称（如"用户服务"、"订单服务"）
• 端口号: 该服务监听的端口（如 8888、8889）
• 启用该配置组: 勾选后，该配置组才会被"启动所有"包含

Mock 接口配置

1. 点击 "添加接口" 按钮

2. 填写以下信息：

   • 接口路径: 例如 /api/user/info 或 /user/info（取决于是否剥离前缀）
   • HTTP方法: ALL、GET、POST、PUT、DELETE、PATCH
   • 状态码: HTTP 响应状态码（默认：200）
   • 延迟(毫秒): 模拟网络延迟（默认：0）
   • 响应模板: 可选，应用内置的成功、分页、空数据、错误或登录过期 JSON 模板
   • Mock数据: JSON 格式的响应数据
   • 启用: 是否启用此 Mock 配置
   • 使用全局 Cookie: 启用后，响应中会带上当前配置组设置的全局 Cookie

3. 需要用模板替换可编辑 Mock 数据区域时，点击“应用模板”

4. 点击“格式化 JSON”按钮，可将 Mock 数据整理为更易阅读的格式

5. 点击 "OK" 保存配置

HTTP 组设置（协议类型 = HTTP）

HTTP 配置组提供额外的 HTTP 专属字段：

• 全局 Cookie: 配置全局 Cookie 值（例如：sessionId=abc123; userId=456）
• HTTPS: 可将该配置组本地监听从 http://localhost:<port> 切换为 https://localhost:<port>，证书使用 PKCS#12 keystore。
• 生成本地证书: 在项目内创建 certs/intercept-wave-local.p12 调试证书；插件不会自动安装到系统或浏览器信任链。
• 路由列表: 一个 HTTP 组内可维护多条 HTTP 路由。配置弹框现在采用“左侧选路由，右侧编辑当前路由”的结构。每条路由包含：
  • 路由名称: 如 API、Frontend
  • 路径前缀: 用于最长前缀匹配，如 /api、/
  • 目标类型: PROXY 转发到上游服务，STATIC 服务本地前端构建产物
  • 目标地址: 转发上游地址，如 http://localhost:8080
  • 静态根目录: 静态路由使用的本地构建产物目录，如 dist 或 frontend/dist
  • 剥离前缀: 是否在 Mock 匹配和转发前先移除当前路由前缀
  • 重写目标路径: 可选，剥离前缀后追加的目标路径基底，如 /v1
  • SPA 兜底路径: 可选，前端路由深链刷新返回 404 时重试的 HTML 入口路径，如 /index.html
  • 静态 SPA 兜底: 静态路由遇到缺失的 HTML 导航路径时，是否返回 index.html
  • 启用 Mock: 是否优先命中该路由自己的 Mock 接口列表
• Mock 接口列表: 每条路由都维护自己的 Mock 列表，路径解释遵循该路由的 路径前缀 + 剥离前缀 + 可选重写目标路径 规则；当前路由的 Mock 列表会直接在右侧编辑区展示。

多路由示例：

• 路由 1：pathPrefix="/"，enableMock=false，targetBaseUrl=http://localhost:4001
• 路由 2：pathPrefix="/api"，enableMock=true，targetBaseUrl=http://localhost:4002

本地网关 / Nginx 迁移

Intercept Wave 可以在本地开发阶段替代常见 nginx 反向代理配置，便于在 IDE 内统一调试、Mock 和转发。它是本地开发网关，不是生产 nginx 替代品。

典型的前端 + 后端 nginx 配置：

server {
  listen 8888;

  location /api/ {
    proxy_pass http://localhost:9000/;
  }

  location / {
    proxy_pass http://localhost:5173/;
    try_files $uri /index.html;
  }
}

等价的 Intercept Wave HTTP 路由：

[
  {
    "name": "API",
    "pathPrefix": "/api",
    "targetType": "PROXY",
    "targetBaseUrl": "http://localhost:9000",
    "staticRoot": "",
    "stripPrefix": true,
    "rewriteTargetPath": "",
    "spaFallbackPath": "",
    "spaFallback": false,
    "enableMock": true
  },
  {
    "name": "Frontend",
    "pathPrefix": "/",
    "targetType": "PROXY",
    "targetBaseUrl": "http://localhost:5173",
    "staticRoot": "",
    "stripPrefix": false,
    "rewriteTargetPath": "",
    "spaFallbackPath": "/index.html",
    "spaFallback": false,
    "enableMock": false
  }
]

这适用于 Vite、Next、Webpack 等前端开发服务器：/api/users 进入后端路由，/、/assets/app.js、/dashboard/settings 进入前端开发服务器。浏览器刷新 /dashboard/settings 遇到上游 404 时，前端路由可通过 spaFallbackPath 重试 /index.html。

多后端微服务可按前缀拆分多条路由，并依赖最长前缀匹配：

[
  { "name": "API", "pathPrefix": "/api", "targetType": "PROXY", "targetBaseUrl": "http://localhost:9000", "staticRoot": "", "stripPrefix": true, "rewriteTargetPath": "", "spaFallbackPath": "", "spaFallback": false, "enableMock": true },
  { "name": "Auth", "pathPrefix": "/auth", "targetType": "PROXY", "targetBaseUrl": "http://localhost:9010", "staticRoot": "", "stripPrefix": true, "rewriteTargetPath": "", "spaFallbackPath": "", "spaFallback": false, "enableMock": true },
  { "name": "Admin API", "pathPrefix": "/admin-api", "targetType": "PROXY", "targetBaseUrl": "http://localhost:9020", "staticRoot": "", "stripPrefix": true, "rewriteTargetPath": "", "spaFallbackPath": "", "spaFallback": false, "enableMock": true },
  { "name": "Frontend", "pathPrefix": "/", "targetType": "PROXY", "targetBaseUrl": "http://localhost:5173", "staticRoot": "", "stripPrefix": false, "rewriteTargetPath": "", "spaFallbackPath": "/index.html", "spaFallback": false, "enableMock": false }
]

如果要直接服务项目内的前端构建产物，可将前端路由切换为 STATIC：

{
  "name": "Frontend Build",
  "pathPrefix": "/",
  "targetType": "STATIC",
  "targetBaseUrl": "",
  "staticRoot": "frontend/dist",
  "stripPrefix": false,
  "rewriteTargetPath": "",
  "spaFallbackPath": "",
  "spaFallback": true,
  "enableMock": false
}

由于 .intercept-wave/config.json 是项目级配置，相对 staticRoot 会按项目根目录解析。目录选择器会把项目内目录保存为相对路径，方便团队共享；项目外绝对路径也允许，但只适用于本机。静态路由不会服务配置的静态根目录之外的文件。

路径重写遵循 nginx-like 本地网关语义：

• pathPrefix="/api"，stripPrefix=true：/api/users 会按 /users 进行 Mock 匹配与转发
• pathPrefix="/backend"，stripPrefix=true，rewriteTargetPath="/v1"：/backend/users 会按 /v1/users 进行 Mock 匹配与转发

本地 HTTPS origin 与 HTTP 复用同一套路由处理链路。启用 HTTP 配置组的 HTTPS 后，可以选择已有 .p12/.pfx 文件，也可以点击“生成本地证书”创建 certs/intercept-wave-local.p12，证书使用 CN=localhost，并包含 localhost 和 127.0.0.1 的 SAN。启用后，该端口只监听 https://localhost:<port>。

等价的 CLI 证书生成命令：

mkdir -p certs
keytool -genkeypair \
  -alias intercept-wave-local \
  -keyalg RSA \
  -keysize 2048 \
  -validity 825 \
  -storetype PKCS12 \
  -keystore certs/intercept-wave-local.p12 \
  -storepass changeit \
  -keypass changeit \
  -dname "CN=localhost, OU=Intercept Wave, O=Local Development, L=Local, ST=Local, C=US" \
  -ext "SAN=dns:localhost,ip:127.0.0.1"

生成的 PKCS#12 包含私钥，仅用于本地调试。浏览器可能仍会提示自签证书不受信任，需要你按本机环境手动信任证书。跨平台 roadmap 链接：IntelliJ #150、VS Code #39、VS Code 文档对应 issue #46。

WebSocket 组设置（协议类型 = WS）

WS 配置组与 HTTP 组共享基础配置（名称、端口、启用），并提供以下 WS 专属选项：

• 上游 WebSocket 地址（可选）: 上游 ws:// 或 wss:// 地址（例如：ws://localhost:8080/ws/chat）。留空时表示“仅本地 WS 服务模式”。
• WS 前缀（可选）: WebSocket 路径匹配前缀；为空时按原始路径匹配。
• 手动推送面板: 控制工具窗口中是否显示 WS 手动推送区域。
• WS 推送规则: 配置弹框现在采用“左侧规则列表，右侧当前规则编辑”的结构：
  • 按路径模式匹配（支持与 HTTP Mock 相同的 */** 通配规则），可选配 JSON 事件键/值。
  • 匹配方向：in（上游 → 客户端）、out（客户端 → 上游）、both（双向）。
  • 推送模式：off、periodic（按秒周期推送，可选在连接建立时 onOpenFire）、timeline（按毫秒时间点依次推送，可选 loop 循环）。
  • 推送消息内容：用于自动推送，同时也作为手动推送的默认模板。
  • 拦截选项：命中规则后可选择拦截，不再向对端转发原始消息。

工具窗口中的 WS 主面板现在会明确区分：

• 本地 WS 服务模式：未配置上游地址，只处理本地客户端连接与推送
• 上游桥接模式：本地 WS 服务同时桥接并转发到上游

路径匹配规则（通配符）

支持在接口路径 path 中使用通配符进行灵活匹配，stripPrefix 的行为保持不变：

• 单段通配 *：匹配一个路径段（不含 /）
  • 例如：/a/b/* 可匹配 /a/b/123，不匹配 /a/b/123/456
• 多段通配 **：匹配多个路径段（可包含 /）
  • 例如：/a/b/** 可匹配 /a/b/123 与 /a/b/123/456
• 段内通配：支持中间位置的 *
  • 例如：/order/*/submit 可匹配 /order/123/submit

优先级（从高到低）：

• 精确路径 > 含通配符但更具体（通配符更少、路径更长）
• 当存在多条同时命中时，优先选择通配符更少、且方法更具体（非 ALL）的规则

注意：

• 匹配仅针对路径（不包含 query string）
• /a/b/** 默认不匹配 /a/b 本身，如需同时匹配可额外添加一条精确 /a/b

4. 启动服务

有两种方式启动服务：

方式 1：启动所有服务

• 点击工具窗口顶部的 "启动所有" 按钮
• 自动启动所有已启用的配置组

方式 2：启动单个服务

• 切换到对应的标签页
• 点击该标签页中的 "启动服务" 按钮
• 只启动当前选中的服务

服务启动成功后：

• 状态显示为 "● 运行中"
• 显示访问地址（如 http://localhost:8888）
• Run 工具窗口会显示实时日志

使用场景

场景 1: 微服务开发

同时 Mock 多个微服务，每个服务独立端口运行：

配置组 1 - 用户服务（端口 8888）：

// 前端代码访问用户服务
fetch('http://localhost:8888/api/user/info')
  .then(res => res.json())
  .then(data => console.log(data));

配置组 2 - 订单服务（端口 8889）：

// 前端代码访问订单服务
fetch('http://localhost:8889/order-api/orders')
  .then(res => res.json())
  .then(data => console.log(data));

配置组 3 - 支付服务（端口 8890）：

// 前端代码访问支付服务
fetch('http://localhost:8890/pay-api/checkout')
  .then(res => res.json())
  .then(data => console.log(data));

所有服务可以同时运行，互不干扰。点击"启动所有"按钮一次性启动所有服务！

场景 2: Mock 特定接口

// 前端代码
fetch('http://localhost:8888/api/user/info')
  .then(res => res.json())
  .then(data => console.log(data));

配置：

• 路径: /api/user/info
• 方法: GET
• Mock 数据:

{
  "code": 0,
  "data": {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com"
  },
  "message": "success"
}

场景 3: 转发未配置的接口

// 这个接口没有配置 Mock，会自动转发到原始服务器
fetch('http://localhost:8888/api/posts')
  .then(res => res.json())
  .then(data => console.log(data));

如果当前路由的上游目标配置为 http://api.example.com，那么实际请求会转发到 http://api.example.com/api/posts。

场景 4: 模拟需要认证的接口

1. 在全局配置中设置 Cookie：sessionId=abc123; userId=456
2. 在 Mock 接口配置中勾选“使用全局 Cookie”
3. Mock 响应会自动附带 Set-Cookie 响应头

场景 5: 模拟网络延迟

在 Mock 配置中设置延迟时间（例如：1000ms），模拟慢速网络环境。

场景 6: 测试不同的响应状态码

配置不同的状态码（404、500等）来测试前端的错误处理逻辑。

配置文件

所有配置保存在项目根目录的 .intercept-wave 文件夹中：

.intercept-wave/
└── config.json           # 全局配置和多配置组

config.json 示例

{
  "version": "5.0",
  "proxyGroups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "网关",
      "port": 8888,
      "httpsEnabled": false,
      "httpsKeystorePath": "",
      "httpsKeystorePassword": "",
      "globalCookie": "sessionId=abc123",
      "enabled": true,
      "routes": [
        {
          "name": "用户 API",
          "pathPrefix": "/api",
          "targetBaseUrl": "http://localhost:9000",
          "stripPrefix": true,
          "enableMock": true,
          "mockApis": [
            {
              "path": "/user/info",
              "enabled": true,
              "mockData": "{\"code\":0,\"data\":{\"name\":\"张三\"}}",
              "method": "GET",
              "statusCode": 200,
              "useCookie": true,
              "delay": 0
            }
          ]
        },
        {
          "name": "订单 API",
          "pathPrefix": "/order-api",
          "targetBaseUrl": "http://localhost:9001",
          "stripPrefix": true,
          "enableMock": false,
          "mockApis": []
        },
        {
          "name": "支付 API",
          "pathPrefix": "/pay-api",
          "targetBaseUrl": "http://localhost:9002",
          "stripPrefix": true,
          "enableMock": false,
          "mockApis": []
        }
      ]
    }
  ]
}

高级功能

全局 Cookie 配置

在全局配置中设置 Cookie 值，多个 Cookie 用分号分隔：

sessionId=abc123; userId=456; token=xyz789

然后在需要带 Cookie 的 Mock 接口中勾选“使用全局 Cookie”，响应时会自动添加 Set-Cookie 响应头。

CORS 支持

Mock 服务器自动添加以下 CORS 头：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

路由级 Header 覆盖

每条 HTTP 路由都可以配置请求头和响应头覆盖规则。请求头规则会在转发上游前应用；响应头规则会在 Mock、代理、静态文件和默认 CORS 头之后应用。规则支持 SET、ADD、REMOVE：

{
  "requestHeaders": [
    {"name": "Authorization", "value": "Bearer local-token", "operation": "SET", "enabled": true},
    {"name": "X-Debug", "value": "1", "operation": "ADD", "enabled": true}
  ],
  "responseHeaders": [
    {"name": "Access-Control-Allow-Origin", "value": "*", "operation": "SET", "enabled": true},
    {"name": "Cache-Control", "value": "no-store", "operation": "SET", "enabled": true}
  ]
}

路由编辑器提供“导入 / 粘贴 Headers”，支持粘贴 Chrome DevTools 原始头、Chrome 格式化 name/value 头、JSON 对象或 JSON 规则数组；保存前会统一归一化为 JSON 规则。受限传输头会保存但运行时跳过：请求侧 host、connection、content-length、date、expect、upgrade、trailer、te；响应侧 transfer-encoding、content-length、connection。

代理模式

未配置 Mock 的接口会自动转发到原始服务器，并保留：

• 原始请求头
• User-Agent
• 请求体（POST/PUT 等）
• Cookie（如果有）

欢迎页面

未配置 / 前端路由时，访问 Mock 服务根路径（http://localhost:8888/）会返回服务状态以及当前路由摘要：

{
  "status": "running",
  "message": "Intercept Wave Mock 服务运行中",
  "configGroup": "网关",
  "server": {
    "port": 8888,
    "scheme": "http",
    "httpsEnabled": false,
    "routes": 3
  },
  "mockApis": {
    "total": 3,
    "enabled": 2
  },
  "routes": [
    {"name": "用户 API", "pathPrefix": "/api", "targetType": "PROXY", "targetBaseUrl": "http://localhost:9000", "staticRoot": "", "stripPrefix": true, "rewriteTargetPath": "", "spaFallbackPath": "", "spaFallback": false, "enableMock": true, "requestHeaders": 1, "responseHeaders": 2, "mockApis": 1},
    {"name": "前端构建", "pathPrefix": "/", "targetType": "STATIC", "targetBaseUrl": "", "staticRoot": "frontend/dist", "stripPrefix": false, "rewriteTargetPath": "", "spaFallbackPath": "", "spaFallback": true, "enableMock": false, "requestHeaders": 0, "responseHeaders": 1, "mockApis": 0}
  ],
  "examples": [
    {"route": "用户 API", "method": "GET", "url": "http://localhost:8888/api/user/info"}
  ]
}

注意事项

1. 端口占用：请确保配置端口未被其他程序占用
2. 配置变更：服务运行中修改配置时，服务可能会自动停止或重启，以便应用最新设置
3. 项目关闭：关闭项目时，正在运行的服务会自动停止
4. 安全性：本工具仅面向本地开发环境，不建议在生产环境中使用

常见问题

Q: 服务启动失败怎么办？

A: 先检查端口是否已被占用，如有需要可在配置中更换端口号。

Q: 接口没有被 Mock？

A: 请确认请求命中了正确的路由，Mock 路径填写无误，并且对应的 Mock 项处于启用状态。

Q: 如何查看请求日志？

A: 启动服务后，IntelliJ IDEA 底部的 Run 工具窗口会自动出现 "Intercept Wave Mock Server" 标签页，实时展示请求日志，包括时间戳、请求方法、路径，以及响应是来自 Mock 还是代理转发。

Q: 支持 HTTPS 吗？

A: 支持。HTTP 配置组可通过 PKCS#12 keystore 将本地监听切换为 https://localhost:<port>；WS 配置组支持本地 ws://，并可通过 PKCS#12 证书启用本地 wss://。

Q: 全局 Cookie 如何工作？

A: 在配置组中设置全局 Cookie 后，再为需要的 Mock 接口勾选“使用全局 Cookie”，响应就会通过 Set-Cookie 响应头将该 Cookie 返回给客户端。

测试与覆盖率

运行单元测试

• 运行全部测试：./gradlew test
• 启动 Robot 测试用 IDE：./gradlew runIdeForUiTests
• 运行 UI 测试（Robot）：./gradlew testUi（在 http://127.0.0.1:8082 就绪后执行）

说明：

• 平台测试在单个 JVM 中运行并启用 headless 配置。
• Remote Robot UI 测试单独拆分到 testUi；其余平台/UI 测试仍归 test。

集成测试（依赖 Docker upstream）

这类测试需要先启动上游服务容器（默认监听 http://localhost:9000，推荐使用 intercept-wave-upstream:v0.3.0）：

• 启动容器：
  • cd docker
  • docker compose -f docker-compose.upstream.yml up -d upstream

测试分类与运行方式：

• 仅运行集成测试（带有 @Category(IntegrationTest) 标记）：
  • ./gradlew test -DincludeTags=org.zhongmiao.interceptwave.tags.IntegrationTest -Diw.upstream.http=http://localhost:9000
• 排除集成测试（只跑纯单元测试）：
  • ./gradlew test -DexcludeTags=org.zhongmiao.interceptwave.tags.IntegrationTest
• 默认行为：
  • 不传入 include/exclude 时会运行全部测试；若未启动容器，依赖上游的测试会自动跳过（运行前会探测可用性）。

可通过以下方式覆盖上游基址：

• 系统属性：-Diw.upstream.http=http://localhost:9000
• 环境变量：IW_UPSTREAM_HTTP=http://localhost:9000

覆盖率报告（Kover）

• XML 报告：./gradlew koverXmlReport → build/reports/kover/report.xml
• HTML 报告：./gradlew koverHtmlReport → build/reports/kover/html/index.html

从覆盖率中排除：

• UI 包：org.zhongmiao.interceptwave.ui、org.zhongmiao.interceptwave.toolWindow
• 适配层包：org.zhongmiao.interceptwave.listeners、org.zhongmiao.interceptwave.startup、org.zhongmiao.interceptwave.events
• UI 相关服务：org.zhongmiao.interceptwave.services.ConsoleService

项目结构（Gradle）

project/
├── build.gradle.kts        # 核心构建：插件、依赖、IntelliJ 配置
├── gradle/
│   ├── changelog.gradle.kts # Changelog 插件配置
│   ├── kover.gradle.kts     # 覆盖率配置与排除
│   ├── test.gradle.kts      # 单元测试任务配置
│   └── ui-test.gradle.kts   # UI 测试与 robot server 配置
├── gradle.properties        # 版本、平台、插件坐标
└── settings.gradle.kts      # Gradle 设置

设计动机：

• 让 build.gradle.kts 聚焦核心配置，易读易维护。
• 将测试/UI/覆盖率/变更日志配置拆分，减少冲突、提升可读性。

项目目录结构

简要的 Gradle 结构见上节“项目结构（Gradle）”。完整的项目目录结构（含模块/包职责）请查看：

• CONTRIBUTING_zh.md：项目结构
• CONTRIBUTING.md：Project Structure

开发计划

• 支持 HTTPS/WSS
• 支持 WebSocket Mock
• 请求日志查看器（已在 Run 工具窗口中实现）
• 导入/导出配置
• Mock 数据模板库
• 支持自定义请求头

反馈与贡献

如有问题或建议，欢迎提交 Issue 或 Pull Request！

许可证

本项目基于 IntelliJ Platform Plugin Template 开发。