242 lines
4.8 KiB
Markdown
242 lines
4.8 KiB
Markdown
|
# 🛠️ 开发指南
|
|||
|
|
|
|||
|
|
> **Development Guide**
|
|||
|
|
|
|||
|
|
本文档面向加入天工智能体平台开发的工程师，涵盖开发环境搭建、编码规范、测试与调试等内容。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、开发环境搭建
|
|||
|
|
|
|||
|
|
### 前置要求
|
|||
|
|
|
|||
|
|
| 工具 | 版本 | 下载 |
|
|||
|
|
|:----|:-----|:-----|
|
|||
|
|
| Node.js | 18+ | [nodejs.org](https://nodejs.org/) |
|
|||
|
|
| pnpm | 8+ | `npm install -g pnpm` |
|
|||
|
|
| Python | 3.11+ | [python.org](https://python.org/) |
|
|||
|
|
| Docker Desktop | 最新 | [docker.com](https://www.docker.com/products/docker-desktop/) |
|
|||
|
|
| Git | 2.30+ | [git-scm.com](https://git-scm.com/) |
|
|||
|
|
| IDE | VSCode / PyCharm | 推荐 VSCode + 对应插件 |
|
|||
|
|
|
|||
|
|
### 推荐 VSCode 插件
|
|||
|
|
|
|||
|
|
- **Vue 开发**：Vue Language Features (Volar)、TypeScript Vue Plugin
|
|||
|
|
- **Python 开发**：Python、Pylance
|
|||
|
|
- **数据库**：MySQL (weijan-chen)
|
|||
|
|
- **Redis**：Redis
|
|||
|
|
- **Docker**：Docker
|
|||
|
|
- **格式化**：Prettier、ESLint
|
|||
|
|
- **Git**：GitLens、Git History
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、代码规范
|
|||
|
|
|
|||
|
|
### 前端规范
|
|||
|
|
|
|||
|
|
#### 命名规范
|
|||
|
|
|
|||
|
|
| 类型 | 规范 | 示例 |
|
|||
|
|
|:----|:-----|:-----|
|
|||
|
|
| 组件名 | PascalCase | `UserProfile.vue` |
|
|||
|
|
| 文件名 | kebab-case | `user-profile.vue` |
|
|||
|
|
| 变量/函数 | camelCase | `getUserList()` |
|
|||
|
|
| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
|
|||
|
|
| Pinia Store | useXxxStore | `useUserStore` |
|
|||
|
|
| CSS 类名 | kebab-case | `.user-avatar` |
|
|||
|
|
|
|||
|
|
#### 组件结构
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<script setup lang="ts">
|
|||
|
|
// 1. 导入
|
|||
|
|
import { ref, computed } from 'vue'
|
|||
|
|
import { useUserStore } from '@/stores/user'
|
|||
|
|
|
|||
|
|
// 2. Props 定义
|
|||
|
|
const props = defineProps<{
|
|||
|
|
userId: string
|
|||
|
|
}>()
|
|||
|
|
|
|||
|
|
// 3. Emits 定义
|
|||
|
|
const emit = defineEmits<{
|
|||
|
|
'update': [data: any]
|
|||
|
|
}>()
|
|||
|
|
|
|||
|
|
// 4. 响应式状态
|
|||
|
|
const loading = ref(false)
|
|||
|
|
|
|||
|
|
// 5. 计算属性
|
|||
|
|
const isAdmin = computed(() => userStore.role === 'admin')
|
|||
|
|
|
|||
|
|
// 6. 方法
|
|||
|
|
async function fetchUser() {
|
|||
|
|
loading.value = true
|
|||
|
|
try {
|
|||
|
|
// ...
|
|||
|
|
} finally {
|
|||
|
|
loading.value = false
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 7. 生命周期
|
|||
|
|
onMounted(() => {
|
|||
|
|
fetchUser()
|
|||
|
|
})
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<template>
|
|||
|
|
<div class="user-profile">
|
|||
|
|
<!-- 模板内容 -->
|
|||
|
|
</div>
|
|||
|
|
</template>
|
|||
|
|
|
|||
|
|
<style scoped lang="scss">
|
|||
|
|
.user-profile {
|
|||
|
|
// 样式
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### Git Commit 规范
|
|||
|
|
|
|||
|
|
遵循 Conventional Commits 规范：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
<type>(<scope>): <subject>
|
|||
|
|
|
|||
|
|
<body>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
| Type | 含义 |
|
|||
|
|
|:-----|:------|
|
|||
|
|
| `feat` | 新功能 |
|
|||
|
|
| `fix` | 修复 Bug |
|
|||
|
|
| `docs` | 文档变更 |
|
|||
|
|
| `style` | 代码格式调整（不影响功能） |
|
|||
|
|
| `refactor` | 重构代码 |
|
|||
|
|
| `perf` | 性能优化 |
|
|||
|
|
| `test` | 添加/修改测试 |
|
|||
|
|
| `chore` | 构建/工具链变更 |
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 示例
|
|||
|
|
feat(agent): 新增智能体知识库关联功能
|
|||
|
|
fix(user): 修复 Token 刷新失败问题
|
|||
|
|
docs(readme): 更新快速开始指南
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 后端规范
|
|||
|
|
|
|||
|
|
#### 项目约定
|
|||
|
|
|
|||
|
|
| 项目 | 约定 |
|
|||
|
|
|:-----|:------|
|
|||
|
|
| 代码风格 | 遵循 PEP 8 |
|
|||
|
|
| 类型注解 | 所有函数必须包含类型注解 |
|
|||
|
|
| 注释 | 关键逻辑需写中文注释 |
|
|||
|
|
| 路由命名 | `/{module}/{action}`，如 `/agents/{id}/start` |
|
|||
|
|
| 响应格式 | 统一使用 `{ code, message, data }` 格式 |
|
|||
|
|
|
|||
|
|
#### 响应格式
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 成功响应
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"message": "success",
|
|||
|
|
"data": { ... }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
# 错误响应
|
|||
|
|
{
|
|||
|
|
"code": 40001,
|
|||
|
|
"message": "用户不存在",
|
|||
|
|
"data": null
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、测试指南
|
|||
|
|
|
|||
|
|
### 前端测试
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd frontend
|
|||
|
|
|
|||
|
|
# 运行单元测试
|
|||
|
|
pnpm test
|
|||
|
|
|
|||
|
|
# 运行测试并生成覆盖率报告
|
|||
|
|
pnpm test:coverage
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 后端测试
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd backend
|
|||
|
|
|
|||
|
|
# 运行所有测试
|
|||
|
|
pytest
|
|||
|
|
|
|||
|
|
# 运行特定模块测试
|
|||
|
|
pytest tests/test_agent.py -v
|
|||
|
|
|
|||
|
|
# 运行测试并生成覆盖率
|
|||
|
|
pytest --cov=app tests/
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、调试技巧
|
|||
|
|
|
|||
|
|
### 前端
|
|||
|
|
|
|||
|
|
- **Vue Devtools**：浏览器安装 Vue Devtools 插件，可查看组件树、状态、事件
|
|||
|
|
- **Axios 拦截器**：在 `utils/request.ts` 中可打印请求/响应的完整信息
|
|||
|
|
|
|||
|
|
### 后端
|
|||
|
|
|
|||
|
|
- **FastAPI 自动文档**：访问 `http://localhost:8037/docs` 交互式调试 API
|
|||
|
|
- **Pdb 调试**：在代码中插入 `import pdb; pdb.set_trace()` 启动断点调试
|
|||
|
|
- **日志查看**：后端日志输出到控制台，关键位置使用 `logger.info()` 打点
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、数据库变更流程
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. 修改 model 文件（如 app/models/user.py）
|
|||
|
|
|
|||
|
|
# 2. 生成迁移脚本
|
|||
|
|
cd backend
|
|||
|
|
alembic revision --autogenerate -m "add_user_avatar_field"
|
|||
|
|
|
|||
|
|
# 3. 审查并执行迁移
|
|||
|
|
alembic upgrade head
|
|||
|
|
|
|||
|
|
# 4. （如需回滚）
|
|||
|
|
alembic downgrade -1
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> ⚠️ **注意**：生产环境的数据库迁移需先在预发布环境验证。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、常见开发问题
|
|||
|
|
|
|||
|
|
| 问题 | 解决方案 |
|
|||
|
|
|:-----|:---------|
|
|||
|
|
| `pnpm install` 报错 | 检查 Node.js 版本，删除 `node_modules` 重新安装 |
|
|||
|
|
| 后端热重载不生效 | 检查 `uvicorn` 是否带 `--reload` 参数 |
|
|||
|
|
| Alembic 检测不到模型变更 | 确认模型已导入 `app/models/__init__.py` |
|
|||
|
|
| CORS 错误 | 检查后端 CORS 配置中 `origins` 是否包含前端地址 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
> 📎 **相关文档**：[快速开始指南](./quickstart.md) | [项目结构概览](./project-structure.md)
|