639 lines
18 KiB
Markdown
639 lines
18 KiB
Markdown
# DevPack 开发指南
|
||
|
||
> 版本：v1.0.0-draft
|
||
> 更新日期：2026-03-03
|
||
> 作者：DevPack Team
|
||
|
||
---
|
||
|
||
## 1. 开发环境搭建
|
||
|
||
### 1.1 前置要求
|
||
|
||
| 工具 | 最低版本 | 安装方式 |
|
||
|------|---------|---------|
|
||
| Go | 1.22+ | [golang.org](https://golang.org/dl/) |
|
||
| Git | 2.30+ | [git-scm.com](https://git-scm.com/) |
|
||
| Make | 3.81+ | 系统包管理器（Windows 推荐用 `choco install make`） |
|
||
| golangci-lint | 1.55+ | `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest` |
|
||
|
||
### 1.2 获取代码
|
||
|
||
```bash
|
||
git clone https://github.com/user/devpack.git
|
||
cd devpack
|
||
```
|
||
|
||
### 1.3 安装依赖
|
||
|
||
```bash
|
||
go mod download
|
||
```
|
||
|
||
### 1.4 验证环境
|
||
|
||
```bash
|
||
# 运行测试
|
||
go test ./...
|
||
|
||
# 构建
|
||
go build -o devpack ./cmd/devpack/
|
||
|
||
# 代码检查
|
||
golangci-lint run
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 项目结构详解
|
||
|
||
```
|
||
DevPack/
|
||
├── cmd/ # 应用入口
|
||
│ └── devpack/
|
||
│ ├── main.go # 主入口
|
||
│ └── commands/ # CLI 命令
|
||
│ ├── root.go # 根命令
|
||
│ ├── init.go # devpack init
|
||
│ ├── scan.go # devpack scan
|
||
│ ├── capture.go # devpack capture
|
||
│ ├── restore.go # devpack restore
|
||
│ ├── diff.go # devpack diff
|
||
│ ├── export.go # devpack export
|
||
│ ├── import.go # devpack import
|
||
│ ├── list.go # devpack list
|
||
│ ├── profile.go # devpack profile
|
||
│ └── version.go # devpack version
|
||
│
|
||
├── internal/ # 内部包
|
||
│ ├── collector/ # 采集器核心
|
||
│ │ ├── collector.go # Collector 接口定义
|
||
│ │ ├── registry.go # 采集器注册中心
|
||
│ │ ├── options.go # 扫描/捕获/还原选项
|
||
│ │ ├── result.go # 结果类型定义
|
||
│ │ │
|
||
│ │ ├── runtime/ # 运行时采集器
|
||
│ │ │ ├── go.go # Go 采集器
|
||
│ │ │ ├── node.go # Node.js 采集器
|
||
│ │ │ ├── python.go # Python 采集器
|
||
│ │ │ ├── java.go # Java 采集器
|
||
│ │ │ ├── rust.go # Rust 采集器
|
||
│ │ │ ├── dotnet.go # .NET 采集器
|
||
│ │ │ └── runtime_test.go # 运行时采集器测试
|
||
│ │ │
|
||
│ │ ├── editor/ # 编辑器采集器
|
||
│ │ │ ├── vscode.go # VS Code 采集器
|
||
│ │ │ ├── jetbrains.go # JetBrains 采集器
|
||
│ │ │ ├── vim.go # Vim/Neovim 采集器
|
||
│ │ │ └── editor_test.go
|
||
│ │ │
|
||
│ │ ├── shell/ # Shell 采集器
|
||
│ │ │ ├── powershell.go # PowerShell 采集器
|
||
│ │ │ ├── bash.go # Bash 采集器
|
||
│ │ │ ├── zsh.go # Zsh 采集器
|
||
│ │ │ ├── fish.go # Fish 采集器
|
||
│ │ │ ├── terminal.go # 终端模拟器配置（Windows Terminal 等）
|
||
│ │ │ └── shell_test.go
|
||
│ │ │
|
||
│ │ ├── pkgmgr/ # 包管理器采集器
|
||
│ │ │ ├── scoop.go # Scoop 采集器
|
||
│ │ │ ├── chocolatey.go # Chocolatey 采集器
|
||
│ │ │ ├── winget.go # Winget 采集器
|
||
│ │ │ ├── homebrew.go # Homebrew 采集器
|
||
│ │ │ ├── apt.go # APT 采集器
|
||
│ │ │ └── pkgmgr_test.go
|
||
│ │ │
|
||
│ │ ├── git/ # Git 配置采集器
|
||
│ │ │ ├── gitconfig.go
|
||
│ │ │ └── git_test.go
|
||
│ │ │
|
||
│ │ ├── env/ # 环境变量采集器
|
||
│ │ │ ├── envvar.go
|
||
│ │ │ └── env_test.go
|
||
│ │ │
|
||
│ │ ├── font/ # 字体采集器
|
||
│ │ │ ├── font.go
|
||
│ │ │ └── font_test.go
|
||
│ │ │
|
||
│ │ └── ssh/ # SSH/GPG 采集器
|
||
│ │ ├── ssh.go
|
||
│ │ └── ssh_test.go
|
||
│ │
|
||
│ ├── pack/ # 打包引擎
|
||
│ │ ├── packer.go # 打包器
|
||
│ │ ├── unpacker.go # 解包器
|
||
│ │ ├── format.go # Pack 格式定义
|
||
│ │ └── pack_test.go
|
||
│ │
|
||
│ ├── restore/ # 还原引擎
|
||
│ │ ├── engine.go # 还原核心逻辑
|
||
│ │ ├── planner.go # 还原计划生成
|
||
│ │ ├── conflict.go # 冲突检测与处理
|
||
│ │ ├── rollback.go # 回滚管理
|
||
│ │ ├── verifier.go # 还原验证
|
||
│ │ └── restore_test.go
|
||
│ │
|
||
│ ├── profile/ # 配置文件管理
|
||
│ │ ├── profile.go # Profile 定义与操作
|
||
│ │ ├── parser.go # YAML 解析
|
||
│ │ └── profile_test.go
|
||
│ │
|
||
│ ├── diff/ # 差异对比
|
||
│ │ ├── differ.go # 差异计算
|
||
│ │ ├── renderer.go # 差异展示
|
||
│ │ └── diff_test.go
|
||
│ │
|
||
│ ├── crypto/ # 加密模块
|
||
│ │ ├── aesgcm.go # AES-256-GCM 实现
|
||
│ │ ├── argon2.go # Argon2id 密钥派生
|
||
│ │ └── crypto_test.go
|
||
│ │
|
||
│ ├── platform/ # 平台适配层
|
||
│ │ ├── platform.go # Platform 接口
|
||
│ │ ├── detect.go # 平台检测
|
||
│ │ ├── windows.go # Windows 实现
|
||
│ │ ├── darwin.go # macOS 实现
|
||
│ │ ├── linux.go # Linux 实现
|
||
│ │ └── platform_test.go
|
||
│ │
|
||
│ ├── config/ # 应用配置
|
||
│ │ ├── config.go # 全局配置
|
||
│ │ └── paths.go # 路径管理
|
||
│ │
|
||
│ ├── ui/ # 终端 UI
|
||
│ │ ├── printer.go # 格式化输出
|
||
│ │ ├── progress.go # 进度条
|
||
│ │ ├── table.go # 表格输出
|
||
│ │ └── prompt.go # 用户交互
|
||
│ │
|
||
│ └── logger/ # 日志
|
||
│ └── logger.go # 日志初始化
|
||
│
|
||
├── pkg/ # 公共包
|
||
│ ├── manifest/ # Pack 清单
|
||
│ │ ├── manifest.go # Manifest 结构定义
|
||
│ │ └── validate.go # Manifest 验证
|
||
│ └── version/ # 版本信息
|
||
│ └── version.go # 版本号管理
|
||
│
|
||
├── plugins/ # 外部插件目录
|
||
│ └── README.md # 插件开发指南
|
||
│
|
||
├── test/ # 集成与端到端测试
|
||
│ ├── e2e/ # 端到端测试
|
||
│ │ ├── capture_restore_test.go
|
||
│ │ └── testdata/ # 测试数据
|
||
│ └── fixtures/ # 测试 fixtures
|
||
│ └── sample-pack/
|
||
│
|
||
├── scripts/ # 脚本
|
||
│ ├── build.sh # 构建脚本
|
||
│ ├── install.sh # 安装脚本
|
||
│ └── release.sh # 发布脚本
|
||
│
|
||
├── .github/
|
||
│ └── workflows/
|
||
│ ├── ci.yml # CI 流水线
|
||
│ └── release.yml # 发布流水线
|
||
│
|
||
├── .golangci.yml # Lint 配置
|
||
├── .gitignore
|
||
├── go.mod
|
||
├── go.sum
|
||
├── Makefile
|
||
├── LICENSE
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 编码规范
|
||
|
||
### 3.1 Go 编码规范
|
||
|
||
遵循 [Effective Go](https://golang.org/doc/effective_go) 和 [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)。
|
||
|
||
#### 命名规范
|
||
|
||
```go
|
||
// ✅ 包名：小写单词，不用下划线
|
||
package collector
|
||
package pkgmgr
|
||
|
||
// ✅ 接口名：动词或名词，单方法接口用 -er 后缀
|
||
type Collector interface { ... }
|
||
type Scanner interface { ... }
|
||
|
||
// ✅ 导出函数/方法：大驼峰
|
||
func NewRegistry() *Registry { ... }
|
||
func (r *Registry) Register(c Collector) error { ... }
|
||
|
||
// ✅ 非导出函数/方法：小驼峰
|
||
func parseVersion(raw string) (string, error) { ... }
|
||
|
||
// ✅ 常量：大驼峰（导出）或小驼峰（非导出）
|
||
const DefaultTimeout = 30 * time.Second
|
||
const maxRetries = 3
|
||
|
||
// ✅ 错误变量：Err 前缀
|
||
var ErrCollectorNotFound = errors.New("collector not found")
|
||
var ErrPackCorrupted = errors.New("pack file corrupted")
|
||
```
|
||
|
||
#### 错误处理
|
||
|
||
```go
|
||
// ✅ 使用 fmt.Errorf 包装错误，提供上下文
|
||
func (c *GoCollector) Scan(ctx context.Context) (*ScanResult, error) {
|
||
version, err := c.detectVersion(ctx)
|
||
if err != nil {
|
||
return nil, fmt.Errorf("go collector: detect version: %w", err)
|
||
}
|
||
// ...
|
||
}
|
||
|
||
// ✅ 自定义错误类型用于需要类型判断的场景
|
||
type CollectorError struct {
|
||
Collector string
|
||
Op string
|
||
Err error
|
||
}
|
||
|
||
func (e *CollectorError) Error() string {
|
||
return fmt.Sprintf("%s: %s: %v", e.Collector, e.Op, e.Err)
|
||
}
|
||
|
||
func (e *CollectorError) Unwrap() error {
|
||
return e.Err
|
||
}
|
||
```
|
||
|
||
#### Context 使用
|
||
|
||
```go
|
||
// ✅ 第一个参数传递 context
|
||
func (c *GoCollector) Scan(ctx context.Context, opts ScanOptions) (*ScanResult, error) {
|
||
// 使用 context 控制超时
|
||
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
|
||
defer cancel()
|
||
|
||
cmd := exec.CommandContext(ctx, "go", "version")
|
||
// ...
|
||
}
|
||
```
|
||
|
||
### 3.2 项目约定
|
||
|
||
| 约定 | 说明 |
|
||
|------|------|
|
||
| 文件命名 | 小写 + 下划线：`go_collector.go`, `scan_result.go` |
|
||
| 测试文件 | `*_test.go` 放在同一包下 |
|
||
| 平台特定 | 使用 Go build tag：`//go:build windows` |
|
||
| 依赖注入 | 通过接口 + 构造函数实现 |
|
||
| 配置 | 使用 Viper，支持文件 + 环境变量 + 命令行参数 |
|
||
| 日志 | 使用 zerolog，结构化日志 |
|
||
|
||
### 3.3 Git 提交规范
|
||
|
||
使用 [Conventional Commits](https://www.conventionalcommits.org/)：
|
||
|
||
```
|
||
<type>(<scope>): <description>
|
||
|
||
[optional body]
|
||
|
||
[optional footer(s)]
|
||
```
|
||
|
||
**类型 (type)：**
|
||
| Type | 说明 |
|
||
|------|------|
|
||
| `feat` | 新功能 |
|
||
| `fix` | Bug 修复 |
|
||
| `docs` | 文档 |
|
||
| `style` | 代码格式 |
|
||
| `refactor` | 重构 |
|
||
| `perf` | 性能优化 |
|
||
| `test` | 测试 |
|
||
| `chore` | 构建/工具 |
|
||
|
||
**Scope 示例：** `collector`, `pack`, `restore`, `cli`, `platform`, `crypto`
|
||
|
||
**示例：**
|
||
```
|
||
feat(collector): add VS Code extension collector
|
||
|
||
Scan and capture VS Code extensions list and settings.
|
||
|
||
Closes #42
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 开发工作流
|
||
|
||
### 4.1 分支策略
|
||
|
||
```
|
||
main (稳定发布)
|
||
│
|
||
├── develop (开发主干)
|
||
│ │
|
||
│ ├── feature/collector-vscode (功能分支)
|
||
│ ├── feature/restore-engine (功能分支)
|
||
│ └── fix/scan-timeout (修复分支)
|
||
│
|
||
└── release/v0.1.0 (发布分支)
|
||
```
|
||
|
||
### 4.2 开发流程
|
||
|
||
1. **创建分支：** `git checkout -b feature/xxx develop`
|
||
2. **开发 & 测试：** 编写代码 + 单元测试
|
||
3. **代码检查：** `make lint`
|
||
4. **提交：** 遵循 Conventional Commits
|
||
5. **推送 & PR：** 推送分支，创建 Pull Request
|
||
6. **Code Review：** 至少一人 Review 通过
|
||
7. **合并：** Squash Merge 到 develop
|
||
|
||
### 4.3 常用 Make 命令
|
||
|
||
```makefile
|
||
# 构建
|
||
make build # 构建当前平台
|
||
make build-all # 构建所有平台
|
||
make build-windows # 构建 Windows 版本
|
||
make build-darwin # 构建 macOS 版本
|
||
make build-linux # 构建 Linux 版本
|
||
|
||
# 测试
|
||
make test # 运行所有测试
|
||
make test-unit # 运行单元测试
|
||
make test-integration # 运行集成测试
|
||
make test-e2e # 运行端到端测试
|
||
make test-coverage # 生成覆盖率报告
|
||
|
||
# 代码质量
|
||
make lint # 运行 golangci-lint
|
||
make fmt # 格式化代码
|
||
make vet # go vet 检查
|
||
|
||
# 开发
|
||
make run # 编译并运行
|
||
make dev # 开发模式（热重载）
|
||
make clean # 清理构建产物
|
||
|
||
# 发布
|
||
make release # 使用 GoReleaser 发布
|
||
make snapshot # GoReleaser 快照（不发布）
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 添加新采集器指南
|
||
|
||
### 5.1 步骤
|
||
|
||
以添加 "Docker" 采集器为例：
|
||
|
||
#### Step 1: 创建采集器文件
|
||
|
||
```go
|
||
// internal/collector/runtime/docker.go
|
||
|
||
package runtime
|
||
|
||
import (
|
||
"context"
|
||
"github.com/user/devpack/internal/collector"
|
||
)
|
||
|
||
// DockerCollector Docker 环境采集器
|
||
type DockerCollector struct{}
|
||
|
||
// 确保实现了 Collector 接口
|
||
var _ collector.Collector = (*DockerCollector)(nil)
|
||
|
||
func NewDockerCollector() *DockerCollector {
|
||
return &DockerCollector{}
|
||
}
|
||
|
||
func (c *DockerCollector) Name() string { return "docker" }
|
||
func (c *DockerCollector) DisplayName() string { return "Docker" }
|
||
func (c *DockerCollector) Description() string {
|
||
return "Captures Docker version, images, and configuration"
|
||
}
|
||
func (c *DockerCollector) Category() collector.Category {
|
||
return collector.CategoryRuntime
|
||
}
|
||
|
||
func (c *DockerCollector) IsAvailable(ctx context.Context) bool {
|
||
_, err := exec.LookPath("docker")
|
||
return err == nil
|
||
}
|
||
|
||
func (c *DockerCollector) Scan(ctx context.Context, opts collector.ScanOptions) (*collector.ScanResult, error) {
|
||
// 实现扫描逻辑
|
||
// 1. 检测 Docker 版本
|
||
// 2. 列出本地镜像
|
||
// 3. 获取 Docker daemon 配置
|
||
return nil, nil
|
||
}
|
||
|
||
func (c *DockerCollector) Capture(ctx context.Context, targetDir string, opts collector.CaptureOptions) error {
|
||
// 实现捕获逻辑
|
||
return nil
|
||
}
|
||
|
||
func (c *DockerCollector) Restore(ctx context.Context, sourceDir string, opts collector.RestoreOptions) error {
|
||
// 实现还原逻辑
|
||
return nil
|
||
}
|
||
|
||
func (c *DockerCollector) Verify(ctx context.Context) (*collector.VerifyResult, error) {
|
||
// 实现验证逻辑
|
||
return nil, nil
|
||
}
|
||
```
|
||
|
||
#### Step 2: 注册采集器
|
||
|
||
```go
|
||
// internal/collector/registry.go 中添加注册
|
||
|
||
func NewDefaultRegistry() *Registry {
|
||
r := NewRegistry()
|
||
|
||
// Runtime collectors
|
||
r.Register(runtime.NewGoCollector())
|
||
r.Register(runtime.NewNodeCollector())
|
||
r.Register(runtime.NewDockerCollector()) // 新增
|
||
// ...
|
||
|
||
return r
|
||
}
|
||
```
|
||
|
||
#### Step 3: 编写测试
|
||
|
||
```go
|
||
// internal/collector/runtime/docker_test.go
|
||
|
||
func TestDockerCollector_Scan(t *testing.T) {
|
||
c := NewDockerCollector()
|
||
|
||
if !c.IsAvailable(context.Background()) {
|
||
t.Skip("Docker not available")
|
||
}
|
||
|
||
result, err := c.Scan(context.Background(), collector.ScanOptions{})
|
||
assert.NoError(t, err)
|
||
assert.NotEmpty(t, result.Items)
|
||
}
|
||
```
|
||
|
||
#### Step 4: 更新文档
|
||
|
||
在 README.md 和 PRD.md 中添加 Docker 采集器的说明。
|
||
|
||
---
|
||
|
||
## 6. 调试指南
|
||
|
||
### 6.1 日志级别
|
||
|
||
```bash
|
||
# 设置日志级别
|
||
DEVPACK_LOG_LEVEL=debug devpack scan
|
||
|
||
# 或通过命令行参数
|
||
devpack scan --log-level debug
|
||
```
|
||
|
||
| 级别 | 用途 |
|
||
|------|------|
|
||
| `trace` | 非常详细的调试信息 |
|
||
| `debug` | 调试信息 |
|
||
| `info` | 正常操作信息（默认） |
|
||
| `warn` | 警告 |
|
||
| `error` | 错误 |
|
||
| `fatal` | 致命错误 |
|
||
|
||
### 6.2 VS Code 调试配置
|
||
|
||
```json
|
||
// .vscode/launch.json
|
||
{
|
||
"version": "0.2.0",
|
||
"configurations": [
|
||
{
|
||
"name": "Debug DevPack Scan",
|
||
"type": "go",
|
||
"request": "launch",
|
||
"mode": "debug",
|
||
"program": "${workspaceFolder}/cmd/devpack",
|
||
"args": ["scan", "--verbose"],
|
||
"env": {
|
||
"DEVPACK_LOG_LEVEL": "debug"
|
||
}
|
||
},
|
||
{
|
||
"name": "Debug DevPack Capture",
|
||
"type": "go",
|
||
"request": "launch",
|
||
"mode": "debug",
|
||
"program": "${workspaceFolder}/cmd/devpack",
|
||
"args": ["capture", "--name", "test-env"],
|
||
"env": {
|
||
"DEVPACK_LOG_LEVEL": "debug"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 6.3 常见问题排查
|
||
|
||
| 问题 | 排查方向 |
|
||
|------|---------|
|
||
| 采集器找不到工具 | 检查 PATH 环境变量，确认工具已安装 |
|
||
| Pack 文件损坏 | 使用 `devpack verify <pack>` 校验 |
|
||
| 还原权限不足 | 以管理员身份运行 |
|
||
| 跨版本不兼容 | 检查 Manifest 中的 format_ver |
|
||
|
||
---
|
||
|
||
## 7. 发布流程
|
||
|
||
### 7.1 版本号规范
|
||
|
||
遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)：
|
||
|
||
```
|
||
MAJOR.MINOR.PATCH[-PRERELEASE]
|
||
|
||
- MAJOR: 不兼容的 API 变更
|
||
- MINOR: 向下兼容的功能新增
|
||
- PATCH: 向下兼容的 Bug 修复
|
||
```
|
||
|
||
### 7.2 发布步骤
|
||
|
||
```bash
|
||
# 1. 确保所有测试通过
|
||
make test
|
||
|
||
# 2. 更新 CHANGELOG
|
||
# 编辑 CHANGELOG.md
|
||
|
||
# 3. 创建 Release Tag
|
||
git tag -a v0.1.0 -m "Release v0.1.0"
|
||
git push origin v0.1.0
|
||
|
||
# 4. GoReleaser 自动构建发布（CI 触发）
|
||
# 或手动：
|
||
make release
|
||
```
|
||
|
||
### 7.3 GoReleaser 配置
|
||
|
||
```yaml
|
||
# .goreleaser.yml
|
||
version: 2
|
||
|
||
builds:
|
||
- main: ./cmd/devpack
|
||
binary: devpack
|
||
env:
|
||
- CGO_ENABLED=0
|
||
goos:
|
||
- windows
|
||
- darwin
|
||
- linux
|
||
goarch:
|
||
- amd64
|
||
- arm64
|
||
ldflags:
|
||
- -s -w
|
||
- -X github.com/user/devpack/pkg/version.Version={{.Version}}
|
||
- -X github.com/user/devpack/pkg/version.Commit={{.Commit}}
|
||
- -X github.com/user/devpack/pkg/version.Date={{.Date}}
|
||
|
||
archives:
|
||
- format: tar.gz
|
||
format_overrides:
|
||
- goos: windows
|
||
format: zip
|
||
|
||
checksum:
|
||
name_template: 'checksums.txt'
|
||
|
||
changelog:
|
||
sort: asc
|
||
filters:
|
||
exclude:
|
||
- '^docs:'
|
||
- '^test:'
|
||
- '^chore:'
|
||
```
|