贡献者必读：WatchYourLAN代码结构与PR流程

贡献者必读：WatchYourLAN代码结构与PR流程

【免费下载链接】WatchYourLAN Lightweight network IP scanner with web GUI 项目地址: https://gitcode.com/GitHub_Trending/wa/WatchYourLAN

引言：为什么需要这份指南？

作为一款轻量级网络IP扫描工具，WatchYourLAN的代码结构清晰、模块化程度高，这为新贡献者提供了良好的入门基础。然而，任何开源项目都有其独特的架构设计和开发规范。本指南将深入剖析WatchYourLAN的代码结构，详解PR流程，并提供实用的开发技巧，帮助你快速融入项目开发，贡献有价值的代码。

读完本文，你将能够：

• 理解WatchYourLAN的前后端代码组织结构
• 掌握核心模块的功能和交互方式
• 熟练运用开发工具和环境配置
• 遵循规范的PR流程提交贡献
• 编写符合项目风格的代码

一、项目整体架构

WatchYourLAN采用前后端分离的架构设计，后端使用Go语言编写，前端则基于Solid.js框架开发。这种架构使得前后端可以独立开发、测试和部署，提高了开发效率和代码可维护性。

1.1 架构概览

1.2 技术栈概览

组件	技术	版本要求
后端语言	Go	1.25.1+
Web框架	Gin	1.10.1+
ORM	GORM	1.30.3+
前端框架	Solid.js	1.9.5+
构建工具	Vite	6.2.0+
类型检查	TypeScript	~5.7.2
数据库	SQLite/PostgreSQL	-
API文档	Swagger	-

二、代码结构详解

2.1 项目目录结构

WatchYourLAN/
├── assets/              # 静态资源
├── backend/             # 后端代码
│   ├── cmd/             # 命令入口
│   ├── configs/         # 配置文件
│   ├── docs/            # API文档
│   ├── internal/        # 内部模块
│   └── ...
├── frontend/            # 前端代码
│   ├── src/             # 源代码
│   ├── public/          # 静态资源
│   └── ...
├── docker-compose.yml   # Docker配置
└── ...

2.2 后端代码结构

后端采用Go语言开发，遵循Go的标准项目布局，同时结合了领域驱动设计的思想，将代码按功能模块划分。

核心模块说明：

1. api: 定义HTTP路由和处理函数，如routes.go中定义了所有API端点。

   // 示例：API路由定义 (internal/api/routes.go)
   func Routes(router *gin.Engine) {
       r0 := router.Group("/api")
       {
           r0.GET("/all", getAllHosts)                // 获取所有主机
           r0.GET("/edit/:id/:name/*known", editHost) // 编辑主机信息
           r0.GET("/host/:id", getHost)               // 获取单个主机详情
           // ... 其他路由
       }
   }
   

2. arp: 实现ARP扫描功能，arpscan.go中的Scan函数是核心。

3. routines: 包含后台任务，如定期扫描网络的scan-routine.go。

   // 示例：扫描任务 (internal/routines/scan-routine.go)
   func startScan(quit chan bool) {
       var lastDate, nowDate, plusDate time.Time
       var foundHosts []models.Host
   
       for {
           select {
           case <-quit:
               return
           default:
               nowDate = time.Now()
               plusDate = lastDate.Add(time.Duration(conf.AppConfig.Timeout) * time.Second)
   
               if nowDate.After(plusDate) {
                   foundHosts = arp.Scan(conf.AppConfig.Ifaces, conf.AppConfig.ArpArgs, conf.AppConfig.ArpStrs)
                   // ... 处理扫描结果
                   lastDate = time.Now()
               }
               time.Sleep(time.Duration(1) * time.Minute)
           }
       }
   }
   

4. gdb: 数据库操作模块，封装了与SQLite/PostgreSQL的交互。

5. notify: 实现通知功能，基于Shoutrrr库支持多种通知方式。

2.3 前端代码结构

前端采用Solid.js框架，组件化设计，代码结构清晰。

核心组件说明：

1. App.tsx: 应用入口，定义路由结构。

   // 示例：路由配置 (src/App.tsx)
   function App() {
     onMount(() => {
       runAtStart();
     });
   
     const Config = lazy(() => import("./pages/Config"));
     const History = lazy(() => import("./pages/History"));
     const HostPage = lazy(() => import("./pages/HostPage"));
   
     return (
       <>
       <Header></Header>
       <div class="container-lg">
         <div class="row">
           <div class="col-md mt-4 mb-4">
             <Router>
               <Route path="/" component={Body}/>
               <Route path="/config" component={Config}/>
               <Route path="/history" component={History}/>
               <Route path="/host/:id" component={HostPage}/>
             </Router>
           </div>
         </div>
       </div>
       </>
     )
   }
   

2. components: 可复用组件，如主机详情卡片HostCard.tsx。

   // 示例：主机卡片组件 (src/components/HostPage/HostCard.tsx)
   function HostCard(_props: any) {
     // ... 组件逻辑
     return (
       <div class="card border-primary">
         <div class="card-header">Host</div>
         <div class="card-body table-responsive">
           <table class="table table-striped table-hover">
             <tbody>
             <tr>
               <td>ID</td>
               <td>{_props.host.ID}</td>
             </tr>
             <tr>
               <td>Name</td>
               <td>
               <input type="text" class="form-control" value={_props.host.Name}
                 onInput={e => handleInput(e.target.value)}></input>
               </td>
             </tr>
             {/* ... 其他表格行 */}
             </tbody>
           </table>
           <button type="button" onClick={handleDel} class="btn btn-outline-danger">Delete host</button>
         </div>
       </div>
     )
   }
   

3. pages: 页面组件，对应不同路由。

4. functions: 工具函数，如API调用、数据处理等。

三、开发环境搭建

3.1 系统要求

• Git
• Go 1.25.1+
• Node.js 16+
• npm/yarn/pnpm
• Docker (可选，用于容器化部署测试)

3.2 代码获取

git clone https://gitcode.com/GitHub_Trending/wa/WatchYourLAN.git
cd WatchYourLAN

3.3 后端开发环境

# 进入后端目录
cd backend

# 安装依赖
go mod tidy

# 运行开发服务器
make run

Makefile常用命令：

命令	功能
make mod	初始化Go模块
make run	运行开发服务器
make fmt	格式化代码
make lint	代码检查
make swag	生成Swagger文档

3.4 前端开发环境

# 进入前端目录
cd frontend

# 安装依赖
npm install

# 运行开发服务器
npm run dev

package.json常用脚本：

命令	功能
npm run dev	启动开发服务器
npm run build	构建生产版本
npm run preview	预览生产构建

3.5 Docker开发环境

# 使用docker-compose启动
docker-compose up -d

四、PR流程详解

4.1 PR流程概览

4.2 详细步骤

1. Fork仓库

   • 访问项目页面: https://gitcode.com/GitHub_Trending/wa/WatchYourLAN
   • 点击"Fork"按钮创建个人副本

2. 克隆到本地

   git clone https://gitcode.com/你的用户名/WatchYourLAN.git
   cd WatchYourLAN
   

3. 创建功能分支

   git checkout -b feature/your-feature-name
   # 或修复bug
   git checkout -b fix/bug-description
   

4. 开发与提交

   • 进行代码开发
   • 提交遵循Conventional Commits规范

   git add .
   git commit -m "feat: add new feature"
   # 或修复bug
   git commit -m "fix: resolve issue with..."
   

5. 保持分支同步

   # 添加上游仓库
   git remote add upstream https://gitcode.com/GitHub_Trending/wa/WatchYourLAN.git
   
   # 拉取上游更新
   git fetch upstream
   
   # 合并到本地分支
   git merge upstream/main
   

6. 推送分支

   git push origin feature/your-feature-name
   

7. 创建Pull Request

   • 在GitHub界面上创建PR
   • 填写PR描述，说明实现的功能或修复的问题
   • 引用相关issue（如果有）

8. 代码审查与修改

   • 等待维护者审查
   • 根据反馈进行修改
   • 修改后推送，PR会自动更新

9. 合并

   • 审查通过后，由维护者合并到主分支

4.3 PR提交规范

PR标题应遵循以下格式：

<类型>[可选作用域]: <描述>

[可选正文]

[可选脚注]

类型包括：

• feat: 新功能
• fix: 错误修复
• docs: 文档更新
• style: 代码风格调整（不影响代码逻辑）
• refactor: 代码重构
• perf: 性能优化
• test: 添加或修改测试
• chore: 构建过程或辅助工具变动

示例：

feat(api): add endpoint for host history

Add a new API endpoint /api/history/:mac to retrieve history records for a specific host by MAC address.

Closes #123

五、代码规范与最佳实践

5.1 Go代码规范

1. 遵循Effective Go和Go Code Review Comments
2. 使用make fmt格式化代码
3. 使用make lint进行代码检查
4. 错误处理：不忽略错误，提供有意义的错误信息
5. 注释：为包、函数、结构体提供清晰注释，特别是导出的标识符

5.2 TypeScript/Solid.js代码规范

1. 使用ESLint和Prettier保持代码风格一致
2. 组件命名：PascalCase，如HostCard.tsx
3. 函数命名：camelCase，如handleInput
4. 组件拆分：遵循单一职责原则，避免过大的组件
5. Props定义：使用TypeScript接口明确定义组件Props类型

5.3 测试规范

虽然当前项目测试覆盖率有限，但贡献新功能时应添加相应测试：

1. 后端：在对应包下创建*_test.go文件
2. 前端：使用Jest和Testing Library进行组件测试
3. 确保新功能有单元测试，关键流程有集成测试

5.4 文档规范

1. API变更需更新Swagger文档：make swag
2. 新功能需更新README.md相关部分
3. 复杂逻辑需添加详细注释

六、贡献指南与建议

6.1 寻找贡献机会

1. Issues：查看带有"good first issue"标签的issues
2. 功能请求：查看带有"enhancement"标签的issues
3. bug修复：查看带有"bug"标签的issues
4. 文档改进：发现文档中的错误或不完善之处

6.2 贡献建议

1. 从小处着手：先从简单的bug修复或小功能开始
2. 充分沟通：在开始工作前，通过issue与维护者沟通
3. 关注质量：注重代码质量而非功能数量
4. 测试先行：编写测试可以帮助你更好地理解现有代码
5. 保持更新：定期同步上游仓库，避免合并冲突

6.3 避免常见问题

1. 不遵循代码规范
2. 提交过大的PR，难以审查
3. 缺少必要的测试
4. 不更新文档
5. 未与维护者提前沟通重大变更

七、结语

感谢你的兴趣和贡献！开源项目的成长离不开每一位贡献者的努力。通过遵循本指南，你可以更高效地参与WatchYourLAN的开发，为项目贡献有价值的代码。

如果你在贡献过程中遇到任何问题，欢迎通过issue或项目讨论区提问。我们期待看到你的精彩贡献！

附录：常用资源

• 项目GitHub页面
• Go官方文档
• Solid.js文档
• Gin框架文档
• GORM文档

【免费下载链接】WatchYourLAN Lightweight network IP scanner with web GUI 项目地址: https://gitcode.com/GitHub_Trending/wa/WatchYourLAN