mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 07:06:43 +08:00
nyaKazuha
5e76ea4ae3
Update the authoritative docs, guides, architecture notes, gap list, deployment guidance, handoff notes, and changelog to reflect the current Rust official resource sync boundary.
196 lines
3.5 KiB
Markdown
196 lines
3.5 KiB
Markdown
# 开发指南
|
||
|
||
## 环境准备
|
||
|
||
### 安装依赖
|
||
|
||
#### Go
|
||
```bash
|
||
# 安装 Go 1.22+
|
||
# 参考：https://golang.org/doc/install
|
||
|
||
go version # 验证安装
|
||
```
|
||
|
||
#### Rust
|
||
```bash
|
||
# 安装 Rust 1.75+
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||
|
||
rustc --version # 验证安装
|
||
cargo --version
|
||
```
|
||
|
||
#### Docker
|
||
```bash
|
||
# 安装 Docker 和 Docker Compose
|
||
# 参考：https://docs.docker.com/get-docker/
|
||
|
||
docker --version
|
||
docker compose version
|
||
```
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
请参考 [架构文档](../architecture/README.md) 了解完整的项目结构。
|
||
|
||
---
|
||
|
||
## 开发工作流
|
||
|
||
### 1. 创建功能分支
|
||
|
||
```bash
|
||
git checkout -b feature/your-feature-name
|
||
```
|
||
|
||
### 2. 开发
|
||
|
||
```bash
|
||
# 实时编译检查
|
||
make check
|
||
|
||
# 运行测试
|
||
make test
|
||
|
||
# 格式化代码
|
||
make fmt
|
||
```
|
||
|
||
### 3. 提交
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "feat: 添加新功能"
|
||
```
|
||
|
||
提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
||
- `feat:` 新功能
|
||
- `fix:` 修复 bug
|
||
- `docs:` 文档更新
|
||
- `style:` 代码格式（不影响功能）
|
||
- `refactor:` 重构
|
||
- `test:` 测试相关
|
||
- `chore:` 构建工具或辅助工具
|
||
|
||
### 4. 推送和 PR
|
||
|
||
```bash
|
||
git push origin feature/your-feature-name
|
||
# 然后在 GitHub 创建 Pull Request
|
||
```
|
||
|
||
---
|
||
|
||
## 代码规范
|
||
|
||
### Go
|
||
- 遵循 [Effective Go](https://golang.org/doc/effective_go)
|
||
- 使用 `gofmt` 格式化
|
||
- 使用 `golangci-lint` 进行静态检查
|
||
|
||
### Rust
|
||
- 遵循 [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
|
||
- 使用 `cargo fmt` 格式化
|
||
- 使用 `cargo clippy` 进行静态检查
|
||
|
||
### TypeScript
|
||
- 遵循 [TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
|
||
- 使用 ESLint 和 Prettier
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
### 当前必跑测试
|
||
|
||
```bash
|
||
cargo test -p bat-adapters -- --nocapture
|
||
cargo test -p bat-ffi -- --nocapture
|
||
cargo test -p bat-infrastructure -- --nocapture
|
||
cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture
|
||
```
|
||
|
||
Go CLI 尚未实现时，`go test ./...` 可能没有产品级 package 可运行；Makefile 会在空 Go 阶段清晰跳过。
|
||
|
||
### 集成测试
|
||
|
||
```bash
|
||
cargo test --workspace
|
||
```
|
||
|
||
带真实本地资源的测试默认不应启用。只有在明确需要时，才通过对应 `BAT_REAL_*` 环境变量读取隔离样本路径。不要默认读取 `/home/wanye/D/BlueArchive` 或任何已有客户端目录。
|
||
|
||
### 官方资源同步手动检查
|
||
|
||
查看参数：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
|
||
```
|
||
|
||
dry-run：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --bin bat-official-sync -- \
|
||
--auto-discover \
|
||
--platforms Windows,Android \
|
||
--output /tmp/ba-official-dev \
|
||
--dry-run
|
||
```
|
||
|
||
开发环境真实下载必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录。
|
||
|
||
### 基准测试
|
||
|
||
```bash
|
||
make bench
|
||
```
|
||
|
||
---
|
||
|
||
## 调试
|
||
|
||
### Go
|
||
使用 Delve 调试器：
|
||
```bash
|
||
go install github.com/go-delve/delve/cmd/dlv@latest
|
||
dlv debug ./cmd/bat
|
||
```
|
||
|
||
### Rust
|
||
使用 rust-lldb 或 rust-gdb：
|
||
```bash
|
||
rust-lldb target/debug/bat-cas-engine
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 1. 编译失败
|
||
|
||
确保安装了所有依赖：
|
||
```bash
|
||
go mod download
|
||
cargo fetch
|
||
```
|
||
|
||
### 2. 测试失败
|
||
|
||
先确认失败是否来自真实网络或本地资源路径。默认测试应使用 fixture/mock，不应依赖官方线上资源或开发机已有资源目录。
|
||
|
||
### 3. FFI 绑定问题
|
||
|
||
重新生成绑定：
|
||
```bash
|
||
cd crates/bat-ffi
|
||
cargo build
|
||
```
|
||
|
||
---
|
||
|
||
更多当前状态请查看 [当前状态](../../CURRENT_STATUS.md) 和 [当前缺口清单](../reports/CURRENT_GAPS.md)。
|