保真层原样移植三块横切服务,删除对应桩,bean 名/包名/签名不动: - 文件 com.dsasp.server.file.*:FileServiceImpl(bean fileService)真实现, 存储后端经替换类 FTPClientTemplate(保包名/类名/签名,FTP→本地盘, 根目录 eip4.file.root 配置化默认 ./data/files,resolveSafe 防 ../ 逃逸); BASE64Decoder→java.util.Base64、ant zip→java.util.zip、commons-codec→MessageDigest。 - 日志 com.dsasp.server.log.*:SystemLogManagerImpl/DataOperatorLogger/ DataLogRecorderImpl + 异步调度(DataLogManager/ProcessLogThread/ProcessSysLogThread) 原样移植,落 SYS_LOG/SYS_DATA_LOG/SYS_DATA_LOGITEM(后者 insert-only 无审计列,§5.1)。 - 消息 com.dsasp.server.mail.*:SystemEmailServiceImpl + SystemEmail/SystemEmailService 移植;SMTP 配置缺省时降级 no-op + WARN,不阻塞启动(§5.38)。 装配/配置/自举/验证: - LegacyXmlWiring 等价补齐三处 jdbcTemplate setter + MainApp.destPath 注入(§4.1); - application.yml 加 eip4.file.root;bootstrap-xservice.sql 自举四张横切表 + LOGLEVEL; - 删除 StubFileService/StubSystemLogManager/StubDataOperatorLog(StubProjectSwitchService 属 viewframework 域非本任务范畴,保留); - 单测 12 + 本地 DB 集成 4,全模块 mvn clean test 绿(含 ArchUnit);8087 启动验证毕已 kill。 报告:platform-auth/P2横切服务实测报告.md;坑入 docs/迁移手册.md §3.1/§3.2/§5.36-5.38。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
11 KiB
P2-3 横切服务真实现实测报告(文件 / 日志 / 消息)
任务:用 framework 真实现替换横切服务桩(文件/日志/消息) 工程:
/Users/zhengwr/workspace/eip3/eip4-platform日期:2026-06-11 必读对照:docs/迁移手册.md(§3.1 替换类、§3.2 横切桩、§4.1 XML 等价装配、§5.1/§5.36/§5.37/§5.38、§5 引擎契约)
一、结论速览
| 维度 | 结果 |
|---|---|
| 移植主源文件 | 18 个(文件 7 + 日志 7 + 消息 3 + MainApp 1),约 1,611 行 |
| 删除的桩 | 3 个(StubFileService / StubSystemLogManager / StubDataOperatorLog) |
| 保留的桩 | 1 个(StubProjectSwitchService —— viewframework 域,非本任务范畴,见 §四) |
| 替换类登记 | FTPClientTemplate(FTP 后端 → 本地盘,保包名/类名/签名),已登记入 §3.1 |
| 新增替换实现 bean | fileService / systemLogManager / dataOperatorLog / dataLogRecorder / systemEmailService |
| 单元 + 集成测试 | 16 个(单测 12 + 本地 DB 集成 4),全绿 |
全模块 mvn clean test |
BUILD SUCCESS(8 模块全绿,含 ArchUnit) |
| 端口 8087 启动 | 正常(0.98s 起;无异常;mail 降级 bean 不阻塞);验证毕已 kill |
| 8084 / 8085 | 未触碰(8084 为并行代理进程,全程保留) |
二、移植面与替换类登记
2.1 文件服务(com.dsasp.server.file.* → platform-legacy-core)
| 文件 | 性质 | 与原版差异 |
|---|---|---|
service/FileServiceImpl.java |
真实现,bean fileService |
sun.misc.BASE64Decoder→java.util.Base64;存储后端经替换类 FTPClientTemplate 走本地盘;其余原样 |
upload/FTPClientTemplate.java |
替换类(§3.1) | FTP 后端 → 本地盘;保包名/类名/对外签名 uploadFileAndZip/downloadFile/delete/fileExists;根目录 MainApp.destPath;resolveSafe 防 ../ 逃逸 |
util/ZipUtil.java |
移植(瘦身) | 仅保留 ZipFileToDest(原 ant zip 重载无调用方,不移植) |
util/FileUtil.java |
移植(瘦身) | 去 javax.swing.FileSystemView 依赖的 getFileType/sortFiles(无调用方) |
util/HashCalc.java |
移植 | commons-codec DigestUtils → JDK MessageDigest,十六进制摘要逐字节一致 |
util/HashEnum.java / util/SysUtil.java |
原样移植 | —— |
common/util/MainApp.java |
配置持有者 | 原版写死 Windows 路径 → 跨平台默认 ./data/files + setter(现代层注入) |
替换类策略落地(§3.1「旧代码零感知」):FileServiceImpl / ZipUtil 对 FTPClientTemplate 的调用一行未改,仅 FTPClientTemplate 内部从 commons-net FTP 客户端换成本地盘读写。本地盘根目录经 eip4.file.root(application.yml,env EIP4_FILE_ROOT 覆盖,默认 ./data/files)由 LegacyXmlWiring 单向写入 MainApp.destPath——保真层不反向依赖现代层(ArchUnit 约束)。
2.2 日志服务(com.dsasp.server.log.* + common/log/service/DataLogRecorder → platform-legacy-core)
原样移植 6 个 impl/调度 + 补 1 个接口:SystemLogManagerImpl(bean systemLogManager)、DataOperatorLogger(bean dataOperatorLog)、DataLogRecorderImpl(bean dataLogRecorder)、DataLogManager(异步调度,Timer 1s/30s)、ProcessLogThread、ProcessSysLogThread、DataLogRecorder(接口)。
落库语义与老系统一致:
- SYS_LOG:
SYS_LOG_ID,TYPE,CONTENT,createtime(joda 毫秒),createby=操作人,updatetime,updateby,isactive=1,version=0。 - SYS_DATA_LOG:
sys_data_log_id,tablename,recordid,mainrecordid,type,updatetime,updateby。 - SYS_DATA_LOGITEM:
sys_data_logitem_id,sys_datalogid,oldvalue,newvalue,columnname—— insert-only,无 UPDATETIME 列(§5.1),实现只走纯 INSERT,符合。
2.3 消息服务(com.dsasp.server.mail.* + common/email/* → platform-legacy-core)
SystemEmailService(接口)+ SystemEmail(bean)原样移植;SystemEmailServiceImpl(bean systemEmailService)降级装配:SMTP 发件人配置(SysConfig 键 com.dsasp.server.mail.admin_mail)缺省时仅打 WARN 后 no-op,不抛、不阻塞启动。原版深度依赖 javax.mail + freemarker + OSGi ConfigUtil + 活的 SMTP,真实投递留口待 JavaMailSender 装配后接通(详见 §5.38)。ClientMailService(POP3/IMAP 全客户端)非「横切消息」范畴且无调用方,本次不移植。
2.4 XML 等价装配补齐(§4.1)
platform-app/.../config/LegacyXmlWiring.java 新增三处 setter 注入(等价原 framework service.xml <property>):
fileService.setJdbcTemplate(jdbcTemplate);
systemLogManagerImpl.setJdbcTemplate(jdbcTemplate);
dataLogRecorder.setJdbcTemplate(jdbcTemplate);
MainApp.setDestPath(fileRoot); // eip4.file.root 注入
三、实测证据
3.1 文件:上传 → 下载字节一致 → 删除(本地盘)
LocalFileStorageTest + XServiceLocalIT#file_upload_download_roundtrip(经容器内真实替换类 FTPClientTemplate):
- 写入二进制载荷 →
uploadFileAndZip落destPath/SYS_DOC/0/itest.zip→fileExists=true; downloadFile解压回字节 →assertArrayEquals(原始, 下载)通过(byte 一致);delete→fileExists=false。- 路径安全:
fileExists("../../etc/passwd")/downloadFile("/a/../../../escape.zip",…)→ 抛IOException+ WARN「拒绝越界附件路径(疑似 ../ 逃逸)」(运行日志已见)。
3.2 日志:CRUD → SYS_LOG / 数据日志表落行,字段语义对
XServiceLocalIT(local profile,本地 eip4m0,经容器内真实 bean):
systemLogManager.log(List)→ SYS_LOG 落行,断言type='Info'、content原值、createby/updateby='tester-001'(操作人)、isactive=1、version=0、createtime>0(joda 毫秒)→ 通过;dataLogRecorder.recorderLogs(List)→ SYS_DATA_LOG + SYS_DATA_LOGITEM 落行,断言主表tablename/recordid/type/updateby、明细columnname='NAME'/newvalue='集成测试客户'/oldvalue=null→ 通过。- 实库残留行(运行后 psql 直查):
sys_data_log: EIP4PT_CUSTOMER | rec-itest | type=1 | tester-002 sys_data_logitem: NAME | 集成测试客户
3.3 消息:配置缺省降级路径(启动无异常、调用打 WARN 不抛)
- 8087 启动日志:
Started Eip4PlatformApplication in 0.981 seconds,无任何 mail 相关异常(降级 bean 装配成功,满足「不阻塞启动」); SystemEmailServiceImplTest+XServiceLocalIT#mail_degrades_without_config:sendEmail在无配置时打 WARN 后 no-op,assertDoesNotThrow通过;运行日志见:WARN ... 邮件服务未配置发件人(com.dsasp.server.mail.admin_mail),降级为 no-op:主题=[...] 收件人=[...]。
3.4 自举脚本
新增 platform-parity/src/main/resources/bootstrap/bootstrap-xservice.sql:幂等建 SYS_DOC / SYS_LOG / SYS_DATA_LOG / SYS_DATA_LOGITEM(后者 insert-only 无审计列)+ 种 LOGLEVEL='Errors,Info,Debug,Warnings'。
3.5 单测清单(16,全绿)
| 测试类 | 数 | 覆盖 |
|---|---|---|
LocalFileStorageTest |
4 | 上传下载字节一致 / ../ 逃逸防护 / 删除 / 缺失下载抛错 |
HashAndFileUtilTest |
3 | MD5 标准向量 / 文件名扩展名解析 / 路径分隔归一 |
SystemLogManagerImplTest |
2 | SYS_LOG 列绑定语义(mock JdbcTemplate)/ deleteByType |
DataLogRecorderImplTest |
1 | SYS_DATA_LOG + LOGITEM 列绑定 + insert-only(无 updatetime) |
SystemEmailServiceImplTest |
2 | 降级 no-op 不抛 / null 安全 |
XServiceLocalIT(集成,本地 DB) |
4 | 系统日志落库 / 数据日志落库 / 附件本地盘往返 / 邮件降级 |
3.6 全模块测试 + ArchUnit
mvn -o clean test → BUILD SUCCESS,8 模块全绿;ArchitectureRulesTest(com.dsasp.. 不得依赖 com.eip4..)通过——三块真实现仅引 com.dsasp + JDK + spring + slf4j,无反向依赖。
备注:一次非 clean 增量 reactor 运行曾出现 ArchUnit 瞬时 FAILURE,经隔离重跑 +
clean test确认为陈旧编译产物(install -DskipTests 先于 parity 新 SQL 上 classpath)所致,非真实违例;clean 全量稳定绿。
四、StubProjectSwitchService 侦察结论(保留,不接管)
StubProjectSwitchService implements com.dsasp.server.common.viewframework.service.ProjectSwitchService,属 viewframework 域(项目上下文切换),不在本任务「文件/日志/消息」范畴。侦察 framework 未见对应的独立横切 impl bundle(file/log/mail 三 bundle 均不含),其真实现归属 viewFramework 域;P2-3 计划未列此项。故按任务约定保留该桩,待 viewFramework 域专项移植时接管。已在 docs/迁移手册.md §3.2 标注。
五、坑列表(已入 docs/迁移手册.md)
| 编号 | 坑 |
|---|---|
| §5.36 | 附件 FileService 原版后端=FTP(非本地盘);本地盘默认须经替换类落地;旧依赖 sun.misc.BASE64Decoder/ant zip/swing 在 JDK17 不可用 |
| §5.37 | 系统/数据日志为异步队列+定时批量落库;bean 名 systemLogManager/dataOperatorLog/dataLogRecorder 三件齐;jdbcTemplate 须 XML 等价 setter 补齐;LOGLEVEL 未配置=整链静默;数据日志仅 ischangelog=1 实体才记 |
| §5.38 | 邮件 SystemEmailServiceImpl 深度依赖外部 SMTP(javax.mail+freemarker+OSGi ConfigUtil),按「配置缺省降级 no-op + WARN」装配,不阻塞启动;ClientMailService(POP3/IMAP)非横切范畴不移植 |
| §3.1 新增行 | FTPClientTemplate 替换类(FTP 后端→本地盘)登记 |
六、变更文件清单
保真层(platform-legacy-core,com.dsasp. 原样移植)*:
com/dsasp/server/common/util/MainApp.javacom/dsasp/server/file/service/FileServiceImpl.java、file/upload/FTPClientTemplate.java、file/util/{ZipUtil,FileUtil,HashCalc,HashEnum,SysUtil}.javacom/dsasp/server/common/log/service/DataLogRecorder.javacom/dsasp/server/log/service/{SystemLogManagerImpl,DataOperatorLogger,DataLogManager,DataLogRecorderImpl,ProcessLogThread,ProcessSysLogThread}.javacom/dsasp/server/common/email/bean/SystemEmail.java、common/email/service/SystemEmailService.java、mail/service/SystemEmailServiceImpl.java- 测试:
file/{LocalFileStorageTest,HashAndFileUtilTest}.java、log/{SystemLogManagerImplTest,DataLogRecorderImplTest}.java、mail/SystemEmailServiceImplTest.java
现代层 / 配置 / 自举:
platform-app/.../config/LegacyXmlWiring.java(新增三处 setter + 文件根注入)platform-app/src/main/resources/application.yml(eip4.file.root)platform-app/.../app/XServiceLocalIT.java(本地 DB 集成测试)platform-parity/src/main/resources/bootstrap/bootstrap-xservice.sql(横切表自举)
删除:platform-auth/.../stub/{StubFileService,StubSystemLogManager,StubDataOperatorLog}.java
文档:docs/迁移手册.md(§3.1 / §3.2 / §5.36-5.38)、本报告