为 Intercept Wave 贡献代码

感谢你关注 Intercept Wave 的贡献工作。本文档会说明如何搭建开发环境、理解项目结构，以及更顺畅地提交改动。

English Version

行为准则

本项目遵循行为准则，所有贡献者都应该遵守。请在所有互动中保持尊重和建设性。

开始贡献

前置要求

在开始之前，请确保你已安装以下工具：

JDK 21 或更高版本
IntelliJ IDEA 2024.1 或更高版本（旗舰版或社区版均可）
Git 版本控制工具
Gradle（项目中已包含 wrapper）

Fork 和 Clone

在 GitHub 上 Fork 本仓库

克隆你的 Fork 到本地：

git clone https://github.com/YOUR_USERNAME/intercept-wave.git
cd intercept-wave

添加上游仓库：

git remote add upstream https://github.com/zhongmiao-org/intercept-wave.git

开发环境设置

1. 在 IntelliJ IDEA 中打开项目

打开 IntelliJ IDEA
选择 File > Open
打开克隆后的仓库目录，选择项目根目录或 build.gradle.kts
以 IntelliJ 项目方式打开，并等待 Gradle 导入完成
等待 Gradle 同步并下载依赖

2. 配置插件 SDK

项目使用 IntelliJ Platform Gradle Plugin，会自动完成插件 SDK 配置，无需手动设置。

3. 运行插件

在沙箱 IntelliJ IDEA 实例中运行插件：

打开 Gradle 工具窗口（View > Tool Windows > Gradle）
导航到 Tasks > intellij > runIde
双击运行

或使用命令行：

./gradlew runIde

项目结构

intercept-wave/
├── .github/                      # CI 配置、Issue 模板
├── .gradle/                      # Gradle 本地缓存（生成）
├── .idea/                        # IDEA 项目文件（本地）
├── build/                        # 构建输出（生成）
├── gradle/
│   ├── changelog.gradle.kts      # Changelog 插件配置
│   ├── kover.gradle.kts          # 覆盖率配置与排除
│   ├── test.gradle.kts           # 单元测试任务配置
│   └── ui-test.gradle.kts        # UI 测试与 robot server 配置
├── src/
│   ├── main/
│   │   ├── kotlin/
│   │   │   └── org/zhongmiao/interceptwave/
│   │   │       ├── services/     # 核心服务（MockServer、Config、Console 适配等）
│   │   │       ├── ui/           # 工具窗口、对话框、控制台订阅者
│   │   │       ├── events/       # 领域事件定义与发布器（消息总线）
│   │   │       ├── listeners/    # IDE 监听器（如项目关闭）
│   │   │       ├── startup/      # 启动活动（订阅者初始化）
│   │   │       ├── model/        # 数据模型（RootConfig、ProxyConfig、MockApiConfig）
│   │   │       └── util/         # 工具类（JSON 归一化、路径匹配、常量）
│   │   └── resources/
│   │       ├── META-INF/plugin.xml           # 插件声明
│   │       ├── messages/InterceptWaveBundle*.properties  # i18n 资源
│   │       └── icons/                         # 插件图标与资源
│   └── test/
│       └── kotlin/
│           └── org/zhongmiao/interceptwave/
│               ├── services/     # 服务层单测（含平台测试）
│               └── ui/           # UI 测试（单独任务 testUi）
├── CHANGELOG.md                  # 英文更新日志
├── CHANGELOG_zh.md               # 中文更新日志
├── README.md                     # 英文说明
├── README_zh.md                  # 中文说明
├── build.gradle.kts              # 核心构建：插件、依赖、IntelliJ 配置
├── gradle.properties             # 版本、平台、插件坐标
└── settings.gradle.kts           # Gradle 设置

核心组件

MockServerService：管理 Mock 服务器的核心服务
ConfigService：处理配置持久化
ConfigDialog：主配置界面
InterceptWaveToolWindowFactory：创建工具窗口 UI
ProjectCloseListener：项目关闭时的清理工作

开发工作流

1. 创建功能分支

git checkout -b feature/your-feature-name

推荐使用以下分支前缀：

feature/ 新功能
fix/ Bug 修复
docs/ 文档变更
refactor/ 代码重构
test/ 测试添加

2. 进行更改

遵循现有的代码风格（参见代码风格）
编写清晰、描述性的提交消息
为新功能添加测试
根据需要更新文档

3. 测试你的更改

提交前运行测试：

./gradlew test

运行 UI 测试（如适用）：

./gradlew testUi

手动测试插件：

./gradlew runIde

4. 保持分支更新

定期与上游仓库同步：

git fetch upstream
git rebase upstream/main

测试

单元测试

位于 src/test/kotlin/，单元测试覆盖各个组件和服务。

运行所有单元测试：

./gradlew test

运行特定测试类：

./gradlew test --tests "org.zhongmiao.interceptwave.services.MockServerServiceTest"

UI 测试

UI 测试使用 IntelliJ 的 Remote Robot 框架，位于 src/test/kotlin/org/zhongmiao/interceptwave/ui/。

运行 UI 测试：

./gradlew testUi

注意：UI 测试通常更耗时、也更占内存，因此与单元测试分开运行。

测试覆盖率

检查测试覆盖率：

./gradlew koverXmlReport

报告将生成在 build/reports/kover/。

手动测试检查清单

手动测试时，建议重点确认以下内容：

插件加载无错误
配置对话框能正确打开和保存
Mock 服务器能正常启动和停止
Mock API 返回预期响应
代理模式正确转发请求
CORS 头部已添加
全局 Cookie 按预期工作
多个代理组独立工作
配置在 IDE 重启后持久化

代码风格

Kotlin 风格

遵循 Kotlin 编码规范：

使用 4 个空格缩进
函数和变量名使用 camelCase
类名使用 PascalCase
最大行长度：120 字符
左大括号放在同一行
在需要清晰性时使用显式类型声明

示例

class ExampleService {
    private var isRunning: Boolean = false

    fun startService(port: Int): Boolean {
        if (isRunning) {
            return false
        }

        // 实现
        isRunning = true
        return true
    }
}

IntelliJ Platform 指南

正确使用 IntelliJ Platform SDK API
避免使用已弃用的 API
正确处理 EDT（事件分发线程）
适当使用应用程序服务和项目服务

提交更改

1. 提交你的更改

编写清晰、描述性的提交消息：

git commit -m "feat: 在 mock 响应中添加自定义头部支持"

遵循约定式提交格式：

feat: 新功能
fix: Bug 修复
docs: 文档变更
test: 测试添加或变更
refactor: 代码重构
chore: 维护任务

2. 推送到你的 Fork

git push origin feature/your-feature-name

3. 创建 Pull Request

前往原始仓库
点击 Pull Requests > New Pull Request
点击 compare across forks
选择你的 fork 和分支
填写 PR 模板，包括：
- 清晰的变更描述
- 相关的 issue 编号（如有）
- 截图（针对 UI 变更）
- 执行的测试

4. PR 审查流程

维护者将审查你的 PR
处理任何反馈或请求的更改
保持你的 PR 与主分支同步
批准后，维护者将合并你的 PR

报告问题

提交 Issue 之前

检查现有 issue 以避免重复
使用最新版本验证问题
收集相关信息

创建 Issue

请包含以下信息：

插件版本：在 Settings > Plugins 中查看
IntelliJ IDEA 版本：Help > About
操作系统：Windows、macOS、Linux
重现步骤：清晰的编号步骤
预期行为：应该发生什么
实际行为：实际发生了什么
截图/日志：如适用
配置：相关的 config.json 内容（已脱敏）

Issue 模板

**插件版本**: 2.0.0
**IntelliJ IDEA 版本**: 2024.1
**操作系统**: macOS 14.0

**描述**
对问题的清晰描述。

**重现步骤**
1. 步骤一
2. 步骤二
3. ...

**预期行为**
你期望发生的事情。

**实际行为**
实际发生的事情。

**截图**
如适用，添加截图。

**其他信息**
任何其他相关信息。

功能建议

我们欢迎功能建议！提交功能请求时：

检查功能是否已存在或已计划
清晰描述功能及其用例
解释为什么这个功能有价值
如可能，提供示例或模型

开发指南

添加新功能

先设计：考虑用户体验和 API 设计
更新模型：在 model/ 中添加或修改数据模型
实现服务逻辑：在 services/ 中添加核心功能
创建 UI 组件：如需要，在 ui/ 中添加 UI
更新配置：如配置变更，修改 ConfigService
添加测试：编写单元测试和 UI 测试
更新文档：更新 README.md 和 CHANGELOG.md

插件配置

插件在 plugin.xml 中配置。关键部分：

Extensions：注册服务、工具窗口等
Actions：定义菜单操作和工具栏按钮
Listeners：注册应用程序和项目监听器

国际化

计划支持多语言。添加 UI 文本时：

将键添加到 messages/InterceptWaveBundle.properties
在代码中使用 InterceptWaveBundle.message("key")
考虑创建特定语言的属性文件

有疑问？

如果你对贡献有疑问：

开启 GitHub Discussion
创建带有 "question" 标签的 issue
查看现有文档和 issue

许可证

当你向 Intercept Wave 提交贡献时，即表示你同意这些贡献将按本项目所使用的同一许可证发布。

感谢你为 Intercept Wave 做出贡献！

Uh oh!

FilesExpand file tree

CONTRIBUTING_zh.md

Latest commit

History