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依赖

核心依赖：

<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 内部资源

• 技术文档
• 代码仓库
• 知识库
• 培训材料