datai/datai-scenes/datai-scene-salesforce/datai-salesforce-integration/techContext.md

# Salesforce数据集成模块 - 技术上下文

## 技术栈概览

本模块基于Java 22和Spring Boot框架构建，采用Maven作为构建工具，使用MyBatis作为持久层框架，集成Salesforce Partner API，实现高效、可靠的数据集成解决方案。

## 1. 开发环境

### 1.1 JDK版本
- **版本**：JDK 22
- **供应商**：OpenJDK / Oracle JDK
- **特性**：
  - 支持最新的Java语言特性
  - 性能优化
  - 安全性增强

### 1.2 构建工具
- **工具**：Maven
- **版本**：3.6+
- **配置**：
  - 编译源码版本：22
  - 编译目标版本：22
  - 编码：UTF-8

### 1.3 IDE
- **推荐IDE**：IntelliJ IDEA
- **插件**：
  - Lombok Plugin
  - MyBatis Plugin
  - Spring Boot Plugin

## 2. 核心框架

### 2.1 Spring Boot
- **版本**：根据父模块版本
- **核心依赖**：
  - spring-boot-starter-web：Web开发
  - spring-boot-starter-aop：AOP支持
  - spring-boot-starter-validation：参数校验
  - spring-boot-starter-cache：缓存支持
  - spring-boot-starter-actuator：监控支持

**关键配置**：
- 自动配置
- 嵌入式服务器（Tomcat）
- 配置外部化
- 健康检查

### 2.2 Spring MVC
- **作用**：Web层框架
- **特性**：
  - RESTful API支持
  - 请求映射
  - 参数绑定
  - 异常处理
  - 拦截器

### 2.3 Spring Security
- **作用**：安全框架
- **特性**：
  - 认证授权
  - 权限控制
  - 方法级安全
  - CSRF防护

### 2.4 Spring AOP
- **作用**：面向切面编程
- **特性**：
  - 日志记录
  - 事务管理
  - 权限控制
  - 性能监控

### 2.5 Spring Cache
- **作用**：缓存抽象
- **特性**：
  - 缓存注解
  - 缓存管理器
  - 多级缓存支持

## 3. 持久层框架

### 3.1 MyBatis
- **版本**：根据父模块版本
- **核心依赖**：
  - mybatis-spring-boot-starter：MyBatis集成
  - mybatis-plus-boot-starter：MyBatis-Plus增强

**特性**：
- SQL映射
- 动态SQL
- 结果映射
- 缓存支持
- 插件机制

**配置**：
- Mapper扫描
- 类型别名
- 配置文件位置

### 3.2 MyBatis-Plus
- **作用**：MyBatis增强工具
- **特性**：
- 通用Mapper
- 通用Service
- 代码生成器
- 分页插件
- 性能分析

## 4. 数据库

### 4.1 数据库类型
- **推荐**：MySQL 8.0+
- **兼容**：PostgreSQL、Oracle、SQL Server

### 4.2 连接池
- **框架**：HikariCP（Spring Boot默认）
- **配置**：
  - 最大连接数：10
  - 最小空闲连接：5
  - 连接超时：30000ms
  - 空闲超时：600000ms

### 4.3 数据库特性
- **事务支持**：ACID
- **隔离级别**：READ_COMMITTED
- **字符集**：UTF-8
- **存储引擎**：InnoDB

## 5. Salesforce API集成

### 5.1 Salesforce Partner API
- **版本**：v56.0+
- **依赖**：
  - salesforce-partner（本地jar包）
  - 路径：src/main/resources/lib/partner.jar

**特性**：
- SOAP协议
- 对象元数据查询
- 数据查询（SOQL）
- 数据操作（DML）

### 5.2 Salesforce REST API
- **版本**：v56.0+
- **特性**：
- RESTful接口
- JSON格式
- OAuth 2.0认证
- 限流控制

### 5.3 Salesforce Bulk API
- **版本**：
  - Bulk API V1：基于SOAP
  - Bulk API V2：基于REST

**特性**：
- 批量数据操作
- 异步处理
- 大数据量支持

## 6. 核心依赖库

### 6.1 日志框架
- **框架**：SLF4J + Logback
- **依赖**：
  - spring-boot-starter-logging
  - lombok（日志注解）

**特性**：
- 日志级别控制
- 日志输出格式
- 日志文件滚动
- 异步日志

### 6.2 JSON处理
- **框架**：Jackson
- **依赖**：
  - spring-boot-starter-web（包含Jackson）

**特性**：
- JSON序列化/反序列化
- 日期时间处理
- 自定义序列化器

### 6.3 工具类库
- **Apache Commons Lang3**：
  - 字符串处理
  - 对象处理
  - 类型转换

- **Apache Commons Collections**：
  - 集合工具
  - 集合操作

- **Hutool**（可选）：
  - 丰富的工具类
  - 简化开发

### 6.4 参数校验
- **框架**：Jakarta Validation
- **依赖**：
  - spring-boot-starter-validation

**特性**：
- 参数校验注解
- 自定义校验器
- 校验分组

### 6.5 API文档
- **框架**：Swagger/OpenAPI 3
- **依赖**：
  - springdoc-openapi-starter-webmvc-ui

**特性**：
- 接口文档生成
- 在线测试
- 接口版本管理

### 6.6 HTTP客户端
- **框架**：OkHttp / Apache HttpClient
- **用途**：
  - REST API调用
  - 文件上传下载

## 7. 中间件

### 7.1 缓存中间件
- **本地缓存**：Caffeine（Spring Boot默认）
- **分布式缓存**：Redis（可选）

**Caffeine配置**：
- 最大容量：10000
- 过期时间：30分钟
- 基于大小的淘汰策略

**Redis配置**（可选）：
- 连接池：Lettuce
- 序列化：Jackson
- 过期策略：TTL

### 7.2 消息队列（可选）
- **框架**：RabbitMQ / Kafka
- **用途**：
  - 异步任务处理
  - 事件驱动
  - 解耦系统

### 7.3 任务调度
- **框架**：Spring @Scheduled
- **特性**：
  - Cron表达式
  - 固定延迟
  - 固定频率

**定时任务**：
- 元数据变更拉取任务
- 限流重置任务
- 数据同步任务

### 7.4 监控中间件
- **框架**：Spring Boot Actuator
- **特性**：
  - 健康检查
  - 指标收集
  - 端点管理

**端点**：
- /actuator/health：健康检查
- /actuator/metrics：指标信息
- /actuator/info：应用信息

## 8. 开发工具

### 8.1 代码生成
- **工具**：MyBatis-Plus Generator
- **功能**：
  - Entity生成
  - Mapper生成
  - Service生成
  - Controller生成

### 8.2 版本控制
- **工具**：Git
- **平台**：GitLab / GitHub

### 8.3 CI/CD
- **工具**：Jenkins / GitLab CI
- **流程**：
  - 代码构建
  - 单元测试
  - 代码扫描
  - 部署

## 9. 测试框架

### 9.1 单元测试
- **框架**：JUnit 5
- **依赖**：
  - spring-boot-starter-test
  - mockito-core

**特性**：
- 测试注解
- Mock支持
- 断言库

### 9.2 集成测试
- **框架**：Spring Boot Test
- **特性**：
- 嵌入式数据库
- 测试配置
- 测试生命周期

### 9.3 性能测试
- **工具**：JMeter / Gatling
- **用途**：
  - 压力测试
  - 性能基准测试

## 10. 部署环境

### 10.1 应用服务器
- **容器**：Tomcat（Spring Boot内置）
- **版本**：9.0+
- **配置**：
  - 最大线程数：200
  - 连接超时：20000ms
  - 接收缓冲区：8192

### 10.2 容器化
- **工具**：Docker
- **镜像**：OpenJDK 22
- **编排**：Docker Compose / Kubernetes

### 10.3 操作系统
- **推荐**：Linux（CentOS 7+ / Ubuntu 18.04+）
- **兼容**：Windows Server、macOS

## 11. 配置管理

### 11.1 配置文件
- **格式**：YAML / Properties
- **位置**：
  - application.yml：主配置
  - application-dev.yml：开发环境
  - application-test.yml：测试环境
  - application-prod.yml：生产环境

### 11.2 配置中心（可选）
- **工具**：Spring Cloud Config / Nacos
- **特性**：
  - 配置集中管理
  - 配置动态刷新
  - 配置版本管理

## 12. 日志管理

### 12.1 日志级别
- **TRACE**：最详细的日志信息
- **DEBUG**：调试信息
- **INFO**：一般信息
- **WARN**：警告信息
- **ERROR**：错误信息

### 12.2 日志输出
- **控制台输出**：开发环境
- **文件输出**：生产环境
- **日志文件**：
  - application.log：应用日志
  - error.log：错误日志
  - access.log：访问日志

### 12.3 日志格式
```
%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n
```

## 13. 监控与告警

### 13.1 应用监控
- **工具**：Spring Boot Actuator + Prometheus
- **指标**：
  - JVM指标
  - HTTP指标
  - 数据库指标
  - 自定义指标

### 13.2 日志监控
- **工具**：ELK Stack（Elasticsearch + Logstash + Kibana）
- **特性**：
  - 日志收集
  - 日志存储
  - 日志分析
  - 日志可视化

### 13.3 告警通知
- **工具**：AlertManager / 钉钉 / 邮件
- **告警规则**：
  - 应用异常
  - 性能下降
  - 资源不足

## 14. 性能优化

### 14.1 JVM优化
- **堆内存**：-Xms2g -Xmx2g
- **新生代**：-Xmn512m
- **垃圾回收器**：G1GC
- **GC日志**：-Xlog:gc*

### 14.2 数据库优化
- **索引优化**：合理创建索引
- **SQL优化**：避免慢查询
- **连接池优化**：调整连接池大小
- **分库分表**：大数据量场景

### 14.3 缓存优化
- **多级缓存**：本地缓存 + 分布式缓存
- **缓存预热**：启动时加载热点数据
- **缓存更新**：定时刷新或事件驱动

## 15. 安全措施

### 15.1 认证安全
- **方式**：JWT / OAuth 2.0
- **加密**：AES-256
- **过期时间**：2小时

### 15.2 通信安全
- **协议**：HTTPS
- **证书**：TLS 1.2+
- **加密算法**：AES-256

### 15.3 数据安全
- **加密存储**：敏感数据加密
- **脱敏展示**：日志和接口脱敏
- **备份策略**：定期备份

## 16. 依赖管理

### 16.1 Maven依赖

**核心依赖**：
```xml
<dependencies>
    <!-- Spring Boot Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-aop</artifactId>
    </dependency>
    
    <!-- MyBatis -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
    </dependency>
    
    <!-- Salesforce Partner API -->
    <dependency>
        <groupId>salesforce</groupId>
        <artifactId>salesforce-partner</artifactId>
        <version>0.0.1</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/src/main/resources/lib/partner.jar</systemPath>
    </dependency>
    
    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    
    <!-- Swagger -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    </dependency>
    
    <!-- Validation -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    
    <!-- Commons -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
    </dependency>
    
    <!-- Test -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

### 16.2 版本管理
- **父模块**：datai-scene-salesforce
- **版本号**：1.0.0
- **版本策略**：统一版本管理

## 17. 开发规范

### 17.1 代码规范
- **命名规范**：驼峰命名法
- **注释规范**：JavaDoc
- **格式规范**：Google Java Style Guide
- **检查工具**：Checkstyle / SpotBugs

### 17.2 Git规范
- **分支策略**：Git Flow
- **提交规范**：Conventional Commits
- **代码审查**：Pull Request

### 17.3 文档规范
- **API文档**：Swagger/OpenAPI
- **技术文档**：Markdown
- **架构文档**：C4 Model

## 18. 技术债务

### 18.1 已知问题
- partner.jar使用system scope，不利于依赖管理
- 缺少单元测试覆盖
- 缺少性能基准测试

### 18.2 改进计划
- 将partner.jar发布到私有Maven仓库
- 增加单元测试覆盖率到80%+
- 建立性能基准测试
- 引入代码质量扫描工具

## 19. 技术选型理由

### 19.1 为什么选择Spring Boot？
- 成熟稳定，社区活跃
- 开箱即用，配置简单
- 生态完善，集成方便
- 微服务友好

### 19.2 为什么选择MyBatis？
- SQL控制灵活
- 性能优秀
- 学习成本低
- 适合复杂查询

### 19.3 为什么选择Salesforce Partner API？
- 功能全面
- 稳定可靠
- 文档完善
- 社区支持好

### 19.4 为什么选择JDK 22？
- 最新特性
- 性能优化
- 长期支持
- 向前兼容

## 20. 未来技术演进

### 20.1 短期计划（3-6个月）
- 引入Redis缓存
- 增加单元测试
- 优化性能
- 完善监控

### 20.2 中期计划（6-12个月）
- 引入消息队列
- 支持分布式部署
- 引入配置中心
- 优化架构

### 20.3 长期计划（12+个月）
- 支持云原生
- 引入Service Mesh
- 支持多云部署
- 构建数据集成平台

## 21. 技术支持

### 21.1 官方文档
- Spring Boot：https://spring.io/projects/spring-boot
- MyBatis：https://mybatis.org/mybatis-3/
- Salesforce API：https://developer.salesforce.com/docs

### 21.2 社区资源
- Stack Overflow
- GitHub Issues
- 技术博客
- 技术论坛

### 21.3 内部资源
- 技术文档
- 代码仓库
- 知识库
- 培训材料