feat(config): integrate etcd-based configuration management
- 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
This commit is contained in:
zhenyi
@@ -0,0 +1,182 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user