BlueArchiveToolkit/docs/guides/development.md

开发指南

环境准备

安装依赖

Go

# 安装 Go 1.22+
# 参考：https://golang.org/doc/install

go version  # 验证安装

Rust

# 安装 Rust 1.75+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

rustc --version  # 验证安装
cargo --version

Docker

# 安装 Docker 和 Docker Compose
# 参考：https://docs.docker.com/get-docker/

docker --version
docker compose version

---

项目结构

请参考 架构文档 了解完整的项目结构。

---

开发工作流

1. 创建功能分支

git checkout -b feature/your-feature-name

2. 开发

# 实时编译检查
make check

# 运行测试
make test

# 格式化代码
make fmt

3. 提交

git add .
git commit -m "feat: 添加新功能"

提交信息遵循 Conventional Commits 规范：

• feat: 新功能
• fix: 修复 bug
• docs: 文档更新
• style: 代码格式（不影响功能）
• refactor: 重构
• test: 测试相关
• chore: 构建工具或辅助工具

4. 推送和 PR

git push origin feature/your-feature-name
# 然后在 GitHub 创建 Pull Request

---

代码规范

Go

• 遵循 Effective Go
• 使用 gofmt 格式化
• 使用 golangci-lint 进行静态检查

Rust

• 遵循 Rust API Guidelines
• 使用 cargo fmt 格式化
• 使用 cargo clippy 进行静态检查

TypeScript

• 遵循 TypeScript Style Guide
• 使用 ESLint 和 Prettier

---

测试

单元测试

# Go
go test ./...

# Rust
cargo test

集成测试

# 需要先启动数据库
make dev

# 运行集成测试
go test -tags=integration ./...

基准测试

make bench

---

调试

Go

使用 Delve 调试器：

go install github.com/go-delve/delve/cmd/dlv@latest
dlv debug ./cmd/bat

Rust

使用 rust-lldb 或 rust-gdb：

rust-lldb target/debug/bat-cas-engine

---

常见问题

1. 编译失败

确保安装了所有依赖：

go mod download
cargo fetch

2. 测试失败

确保数据库已启动：

make dev

3. FFI 绑定问题

重新生成绑定：

cd crates/bat-ffi
cargo build

---

更多问题请查看 FAQ（待创建）或提交 Issue。