zhenyi
7b8d0714e7
- Add etcd-client dependency with TLS support - Implement EtcdConfig struct for reading config values with priority: etcd > env > default - Add ServiceRegistry for service discovery registration in etcd - Create from_etcd method in AppConfig for loading SMTP configuration - Update main.rs to use etcd-based config loading with fallback mechanism - Add etcd module with client connection and key-value operations - Modify Dockerfile to use cargo-chef for faster builds - Add docker-compose.yaml for emailks service deployment - Include AGENTS.md with development guidelines and best practices - Add build.sh script for podman-based container building - Update dependencies in Cargo.toml and Cargo.lock
183 lines
5.4 KiB
Markdown
183 lines
5.4 KiB
Markdown
# AGENTS.md — 开发规范 / Development Guidelines
|
|
|
|
> 本文件为所有 AI 编码助手（Claude Code、pi、Cursor 等）提供统一的开发指导。
|
|
> This file provides unified development guidelines for all AI coding assistants.
|
|
|
|
**最后更新 / Last Updated**: 2026-06-11
|
|
|
|
---
|
|
|
|
## 1. 语言 / Language
|
|
|
|
**Always respond in Chinese (中文).** Use the user's language for all conversations and explanations. Code, commands, and technical terms can remain in English.
|
|
|
|
始终使用中文回复。代码、命令和技术术语可以保留英文。
|
|
|
|
---
|
|
|
|
## 2. 代码风格 / Code Style
|
|
|
|
### 2.1 基本原则 / Basic Principles
|
|
|
|
| 规则 / Rule | 说明 / Description |
|
|
|-----------|-------------------|
|
|
| 遵循现有风格 | Follow existing project conventions |
|
|
| 有意义命名 | Use meaningful variable names |
|
|
| 函数长度 | Keep functions under **50 lines** |
|
|
| 嵌套深度 | Maximum nesting depth: **3 levels** |
|
|
| 注释 | Add comments for complex logic only |
|
|
|
|
### 2.2 Rust 最佳实践 / Rust Best Practices
|
|
|
|
| 规则 / Rule | 说明 / Description |
|
|
|-----------|-------------------|
|
|
| 错误传播 | Use `?` operator; never use `unwrap()` in non-test code |
|
|
| `unsafe` | Avoid; if necessary, add `// SAFETY:` comment |
|
|
| `clone()` | Minimize usage; prefer references |
|
|
| 魔法数字 | No magic numbers; use named constants |
|
|
| 硬编码字符串 | No hardcoded strings; use enums or constants |
|
|
|
|
### 2.3 导入规范 / Import Guidelines
|
|
|
|
```rust
|
|
// 标准库 → 第三方 crate → 本地模块
|
|
use std::collections::HashMap;
|
|
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
use crate::error::{AppError, AppResult};
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 禁止模式 / Forbidden Patterns
|
|
|
|
以下代码模式在项目中严格禁止：
|
|
|
|
| 禁止项 / Forbidden | 说明 / Reason |
|
|
|-------------------|--------------|
|
|
| `// ── xxxx ──────────` | 禁止使用此类分隔线注释 |
|
|
| `unwrap()` / `expect()` (非测试) | 使用 `?` 或安全替代 |
|
|
| `panic!()` / `unreachable!()` | 使用错误类型替代 |
|
|
| 未处理的 `todo!()` | 必须有对应的 issue 追踪 |
|
|
| 注释掉的代码 | 使用 Git 历史追溯 |
|
|
| 过深嵌套 (≥4层) | 使用 early return 扁平化逻辑 |
|
|
| 过长函数 (>50行) | 拆分为更小的函数 |
|
|
| 魔法数字 | 使用 `const` 定义命名常量 |
|
|
| 硬编码字符串 | 使用枚举或常量 |
|
|
|
|
---
|
|
|
|
## 4. 错误处理 / Error Handling
|
|
|
|
### 4.1 错误处理原则
|
|
|
|
| 原则 / Principle | 说明 / Description |
|
|
|----------------|-------------------|
|
|
| 显式处理 | Handle all errors explicitly; no silent failures |
|
|
| 用户友好 | Internal errors are logged; user-facing messages should be helpful |
|
|
| 错误上下文 | Use `.context()` or `.map_err()` to add context |
|
|
|
|
### 4.2 错误日志格式
|
|
|
|
```rust
|
|
tracing::error!(
|
|
error = %err,
|
|
operation = "operation_name",
|
|
"Failed to perform operation"
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 安全规范 / Security
|
|
|
|
| 规则 / Rule | 说明 / Description |
|
|
|-----------|-------------------|
|
|
| 密钥管理 | Never hardcode secrets or API keys |
|
|
| 输入验证 | Always validate and sanitize user input |
|
|
| SMTP 安全 | Use TLS for SMTP connections |
|
|
| 密码安全 | Use proper hashing (Argon2, bcrypt) |
|
|
|
|
---
|
|
|
|
## 6. 工作流程 / Workflow
|
|
|
|
### 6.1 开发流程
|
|
|
|
1. **理解先于编写** — Read before write; understand context first
|
|
2. **最小变更** — Minimal changes; don't refactor unrelated code
|
|
3. **验证变更** — Verify after changes; run tests or check output
|
|
|
|
### 6.2 AI 助手工作规范
|
|
|
|
| 规则 / Rule | 说明 / Description |
|
|
|-----------|-------------------|
|
|
| 先读后写 | Always read existing code before making changes |
|
|
| 最小侵入 | Make minimal changes |
|
|
| 验证结果 | Run `cargo check` or `cargo test` after changes |
|
|
| 解释变更 | Explain what you changed and why |
|
|
|
|
### 6.3 常用命令 / Common Commands
|
|
|
|
```bash
|
|
cargo build # 构建 / Build
|
|
cargo check # 快速检查 / Quick check
|
|
cargo test # 运行测试 / Run tests
|
|
cargo clippy # Lint 检查 / Lint checks
|
|
cargo fmt # 格式化 / Format code
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Git 规范 / Git Workflow
|
|
|
|
### 7.1 提交信息格式
|
|
|
|
```
|
|
<type>(<scope>): <subject>
|
|
|
|
[optional body]
|
|
|
|
[optional footer]
|
|
```
|
|
|
|
| Type | 说明 / Description |
|
|
|------|-------------------|
|
|
| `feat` | 新功能 / New feature |
|
|
| `fix` | Bug 修复 / Bug fix |
|
|
| `refactor` | 重构 / Code refactoring |
|
|
| `docs` | 文档 / Documentation |
|
|
| `test` | 测试 / Tests |
|
|
| `chore` | 构建/工具 / Build/tooling |
|
|
|
|
### 7.2 提交原则
|
|
|
|
| 原则 / Principle | 说明 / Description |
|
|
|----------------|-------------------|
|
|
| 原子提交 | Each commit should address one concern |
|
|
| 完整性 | Each commit should leave the codebase in a working state |
|
|
| 禁止强制推送 | Never force push to main branch |
|
|
|
|
---
|
|
|
|
## 附录 / Appendix
|
|
|
|
### 项目架构速查 / Quick Architecture Reference
|
|
|
|
```
|
|
emailks — 邮件发送服务 / Email Sending Service
|
|
|
|
email.rs → 邮件发送核心 / Email sending core
|
|
server.rs → gRPC 服务 / gRPC server
|
|
queue.rs → 邮件队化 / Email queue
|
|
status.rs → 状态管理 / Status management
|
|
error.rs → 错误类型 / Error types
|
|
config.rs → 配置管理 / Configuration
|
|
proto/ → Protobuf 定义 / Protobuf definitions
|
|
```
|
|
|
|
---
|
|
|
|
*This document is maintained by the development team. For questions or suggestions, please open an issue.*
|