DatomsDBS 开发者快速入门指南

🚀 快速开始

1. 环境准备

# 克隆项目
git clone <repository-url>
cd datomsDBS

# 安装依赖
npm install

# 启动测试数据库（Docker）
cd tests/db_source
docker-compose -f docker-compose-test-dbs.yml up -d
cd ../..

# 启动服务
npm run dev

2. 验证安装

# 访问健康检查接口
curl http://localhost:9000/api/health

# 访问管理界面
open http://localhost:9000/admin

🏗️ 核心架构一图览

┌─────────────────────────────────────────────────────────────┐
│                     DatomsDBS 系统架构                        │
├─────────────────────────────────────────────────────────────┤
│  前端层     │ Public/Admin (HTML+CSS+JS)                     │
├─────────────────────────────────────────────────────────────┤
│  API层      │ Express Routes + Controllers + Middleware     │
├─────────────────────────────────────────────────────────────┤
│  服务层     │ DataSource │ DataAsset │ Auth │ File Services  │
├─────────────────────────────────────────────────────────────┤
│  连接器层   │ MySQL │ PostgreSQL │ MongoDB │ Files │ APIs    │
├─────────────────────────────────────────────────────────────┤
│  数据层     │ DatomsDB Engine + File Storage + Metadata     │
└─────────────────────────────────────────────────────────────┘

📁 关键文件定位

🔥 最重要的文件（新手必看）

1. src/server.js - 服务器入口，了解整个系统启动流程
2. src/api/routes/index.js - 主路由配置，了解API结构
3. src/db/engine.js - 数据库引擎，核心数据操作
4. src/services/dataSourceService.js - 数据源管理，业务核心逻辑

🎯 功能模块快速定位

功能需求	主要文件位置
用户登录认证	src/api/controllers/authController.js
添加数据源	src/services/dataSourceService.js
数据库连接	src/connectors/*.js
数据资产管理	src/api/controllers/dataAssetController.js
权限控制	src/api/controllers/accessController.js
文件上传	src/services/FileStorageService.js
API 路由	src/api/routes/*.js

🔧 常见开发任务

1. 添加新的数据源连接器

// 在 src/connectors/ 创建新文件
// 例如: oracle-connector.js

class OracleConnector {
  async connect(config) {
    // 实现连接逻辑
  }
  
  async query(sql) {
    // 实现查询逻辑
  }
  
  async disconnect() {
    // 实现断开连接逻辑
  }
}

// 在 src/connectors/index.js 注册
module.exports = {
  // ... 其他连接器
  oracle: require('./oracle-connector'),
};

2. 添加新的API端点

// 1. 在 src/api/routes/ 创建路由文件
// 2. 在 src/api/controllers/ 创建控制器
// 3. 在 src/api/routes/index.js 注册路由

// 示例：src/api/routes/newFeatureRoutes.js
const express = require('express');
const router = express.Router();
const controller = require('../controllers/newFeatureController');

router.get('/', controller.getAll);
router.post('/', controller.create);

module.exports = router;

// 在 src/api/routes/index.js 注册
router.use('/new-feature', combinedAuth, newFeatureRoutes);

3. 修改数据库Schema

// 在 src/db/engine.js 的 createDatabase 函数中
// 修改 schema 定义
const schema = {
  id: 'string',
  name: 'string',
  email: 'string',
  created_at: 'string',
  // 添加新字段
  new_field: 'string'
};

🧪 开发测试流程

1. 单元测试

# 运行所有测试
npm test

# 运行特定测试文件
npm test -- --testPathPattern=dataSource

# 监听模式
npm run test:watch

2. 集成测试

# 启动测试数据库
cd tests/db_source
docker-compose -f docker-compose-test-dbs.yml up -d

# 运行集成测试
npm run test:integration

3. 手动测试

# 使用测试脚本
cd tests/dev_to_prod
python dev_pro_test.py

# 或使用 curl 测试 API
curl -X POST http://localhost:9000/api/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

🔍 调试技巧

1. 查看日志

# 实时查看日志
tail -f server.log

# 或在代码中添加
const logger = require('./utils/logger');
logger.info('调试信息', { data: someData });

2. 数据库状态检查

# 检查数据库列表
curl http://localhost:9000/api/datoms/databases

# 检查数据源
curl -H "Authorization: Bearer <token>" \
  http://localhost:9000/api/data-sources

3. 测试数据库连接

# MySQL
mysql -h localhost -P 3306 -u testuser -p testdb

# PostgreSQL  
psql -h localhost -p 15432 -U testuser -d testdb

# MongoDB
mongosh "mongodb://root:rootpass123@localhost:27017/testdb?authSource=admin"

📝 代码规范

1. 文件命名

• 控制器: xxxController.js
• 服务: xxxService.js
• 路由: xxxRoutes.js
• 连接器: xxx-connector.js

2. 函数命名

• 异步函数使用 async/await
• 错误处理使用 try/catch
• 日志记录使用 logger

3. 错误处理模式

async function someFunction() {
  try {
    const result = await someAsyncOperation();
    logger.info('操作成功', { result });
    return result;
  } catch (error) {
    logger.error('操作失败', { error: error.message });
    throw new Error(`操作失败: ${error.message}`);
  }
}

🚨 常见问题解决

1. 端口被占用

# 查找占用端口的进程
lsof -i :9000

# 杀死进程
kill -9 <PID>

2. 数据库连接失败

# 检查测试数据库是否启动
docker ps

# 重启测试数据库
cd tests/db_source
docker-compose -f docker-compose-test-dbs.yml restart

3. 文件权限问题

# 检查 data 目录权限
ls -la data/

# 修复权限
chmod -R 755 data/

4. npm 依赖问题

# 清除缓存
npm cache clean --force

# 删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install

🎯 开发建议

1. 开发顺序建议

1. 先理解现有的数据源连接器实现
2. 参考现有的控制器和服务模式
3. 从简单的 GET 接口开始
4. 逐步添加复杂的业务逻辑
5. 编写测试确保功能正确

2. 调试策略

1. 使用 console.log 或 logger.info 追踪执行流程
2. 利用浏览器开发者工具调试前端
3. 使用 Postman 或 curl 测试 API
4. 查看数据库状态确认数据操作

3. 性能注意事项

1. 大文件处理使用流式读取
2. 数据库查询避免 N+1 问题
3. 合理使用缓存减少重复计算
4. 异步操作避免阻塞主线程

---

📞 获取帮助

• 查看 README.md 了解详细配置
• 阅读 docs/ 目录下的技术文档
• 运行测试用例了解功能使用方式
• 查看现有代码中的注释和示例

新手建议从 src/server.js 开始，跟随代码执行流程理解整个系统！