1. 迁移前最容易被忽略的一步把 IBM MQ 对象盘清楚Jakarta EE 项目迁移大家第一反应往往是改javax.*到jakarta.*的包名、升级应用服务器、重编 EJB。但真正让迁移卡在最后一公里的通常是消息中间件那部分代码里JMSDestinationDefinition声明的队列、glassfish-resources.xml里配的 JNDI、MDB 上挂的持久订阅散落在十几个模块里没人能一口说清到底要在 IBM MQ 上建多少个对象。我见过太多团队在迁移当天才发现应用启动报JMSDestinationNotFoundException或者消息发出去没人消费回头翻代码才发现某个java:module/jms/newsTopic从来没在 MQ 上定义过。这类问题的根因不是技术难而是盘点环节缺失——迁移前没有一份可信的 MQ 对象清单。这篇要解决的就是这件事用 Claude Code 读取 Jakarta EE 项目的配置文件和源码把队列管理器、本地队列、主题、通道、持久订阅、连接工厂这些对象全部提取出来生成一份可以直接照着在 IBM MQ 上执行的清单。适合正在做 Jakarta EE 迁移、项目里用了 IBM MQ 或 JMS 的团队尤其是那种模块多、JNDI 命名不统一、前任开发已经离职的项目。核心检索词先摆出来Claude Code 负责读代码和配置Jakarta EE 是迁移目标IBM MQ 是消息中间件队列管理器和消息中间件对象是盘点产物。下面从环境准备讲到验证动作每一步都能直接复制。2. 前置准备TaoToken 通道与 Claude Code 接入Claude Code 本身是个命令行 Agent能读文件、跑搜索、写文档。要让它分析项目得先让它能连上模型。这里用 TaoToken 提供的统一 Key/API 通道一个 Key 就能调 Claude 系列模型不用分别去各家开账号。TaoToken 官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址不带 UTMhttps://taotoken.net/api接入前先在控制台创建一个 API Key然后配置到 Claude Code 的环境变量里。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量把 base URL 指向 TaoToken 的 API 地址即可。# 写入 shell 配置按你实际用的 shell 选一个 echo export ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.bashrc echo export ANTHROPIC_API_KEYsk-你的TaoToken密钥 ~/.bashrc source ~/.bashrc # 验证变量生效 echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8如果你用的是 zsh把~/.bashrc换成~/.zshrc。Windows 下在 PowerShell 里用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api临时设置或者写进系统环境变量。Key 的创建入口在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注意API Key 只显示一次创建后立刻复制保存。不要把它提交进 Git 仓库建议放在本地环境变量或.env文件里并加进.gitignore。环境变量配好后进入你的 Jakarta EE 项目根目录直接运行claude启动。第一次启动它会让你确认工作目录确认后就能开始对话。如果启动时报连接错误先检查 base URL 有没有多写斜杠、Key 有没有过期。3. 可复制的 Claude Code 提示词与 settings.json 配置3.1 settings.json 配置骨架Claude Code 支持项目级配置放在项目根目录的.claude/settings.json。这个文件可以预设权限、忽略目录、环境变量避免每次分析时它去翻target/、node_modules/这些无关目录浪费时间。{ permissions: { allow: [ Read, Glob, Grep, Write ], deny: [ Bash(rm:*), Bash(git push:*) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api }, ignorePatterns: [ target/**, build/**, node_modules/**, *.class, *.jar ] }permissions.allow里放开 Read、Glob、Grep、Write是因为分析任务需要读文件、按模式搜代码、最后写分析文档。deny里挡掉删除和推送防止 Agent 误操作。ignorePatterns把编译产物排除能显著减少它扫描的文件量。注意env里只放 base URL不要把 API Key 写进 settings.json那个文件可能被提交。Key 继续走系统环境变量。3.2 分析提示词配置就绪后在 Claude Code 里输入下面这段提示词。它的设计思路是先让 Agent 全项目扫描 JMS 相关代码再按对象类型分类提取最后输出结构化清单。分析当前 Jakarta EE 项目中所有涉及 JMS / IBM MQ 的代码和配置目标是生成一份迁移到 IBM MQ 9.4 后需要创建的对象清单。 请按以下步骤执行 1. 搜索所有 JMS 相关文件包括但不限于 - glassfish-resources.xml、*-resources.xml - 含 JMSDestinationDefinition、JMSConnectionFactoryDefinition 的 Java 文件 - 含 MessageDriven、ActivationConfigProperty 的 MDB - 含 ConnectionFactory、Queue、Topic、JMSContext 的代码 - server.xml、domain.xml 等应用服务器配置 2. 提取并分类以下对象 - 连接工厂ConnectionFactoryJNDI 名称、ClientId、连接池参数 - 本地队列Queue物理名称、JNDI 名称、定义方式XML 还是注解、使用模块 - 主题Topic物理名称、JNDI 名称、定义方式、使用模块 - 持久订阅Durable Subscription订阅名、ClientId、所在模块 - 消息选择器Message Selector表达式、所在模块 - 事务模式每个模块用的是 AUTO_ACKNOWLEDGE、CLIENT_ACKNOWLEDGE 还是 SESSION_TRANSACTED 3. 判断需要几个队列管理器。注意 IBM MQ 单个队列管理器原生同时支持点对点队列和发布订阅主题不要默认拆成多个。 4. 输出一份 Markdown 文档到 docs/ibm-mq-migration-analysis.md包含 - 对象总清单表格 - 队列管理器设计方案及理由 - 每个队列管理器需要创建的 MQSC 命令 - JNDI 到 IBM MQ 物理名称的映射表 不要修改任何业务代码只读分析。这段提示词的关键在于第 3 步。很多 Agent 第一次分析时会过度设计把点对点队列和发布订阅主题拆到不同队列管理器理由是避免干扰。但实际上 IBM MQ 一个队列管理器就能同时承载两种模型教学示例或独立运行的模块根本不需要拆。提示词里明确点出这一点能省掉一轮返工。3.3 让 Agent 先探索再写文档如果你不想一次性给太长提示词可以分两步。第一步只让它探索先不要写文档。用 Glob 和 Grep 找出项目里所有 JMS 相关的文件和注解列出文件路径和它们涉及的对象类型等我确认后再深入。确认它找全了再发第二步基于刚才的发现逐个读取这些文件提取队列、主题、连接工厂、持久订阅的完整信息写入 docs/ibm-mq-migration-analysis.md。这种分步方式适合模块特别多的项目你能在中间介入纠正方向。4. 验证请求与成功结果4.1 验证 Agent 是否真的读到了配置分析跑完后别急着信文档。先做几个交叉验证。第一让它列出它实际读过的文件清单列出你这次分析中读取过的所有文件路径以及每个文件里提取到的 JMS 对象数量。拿这个清单和你自己find . -name *.xml | xargs grep -l jms的结果对比看有没有漏掉的文件。第二抽查一个模块。比如项目里有clientsessionmdb这个模块直接问clientsessionmdb 模块里定义了哪些 JMS 对象它们的 JNDI 名称和物理名称分别是什么然后你自己打开那个模块的源码核对。如果 Agent 说的和代码一致说明提取逻辑可靠。4.2 验证 MQ 对象清单的完整性文档生成后重点核对三类容易漏的对象。第一类是注解定义的队列和主题。JMSDestinationDefinition写在 Java 代码里不像 XML 那么显眼Agent 如果只搜 XML 就会漏。检查文档里有没有把这类对象列全。第二类是动态创建的临时队列。代码里用session.createTemporaryQueue()或JMSReplyTo的地方这些不需要在 MQ 上预定义但要在文档里标注出来否则迁移时会误以为漏了。第三类是持久订阅。持久订阅的队列通常由 MQ 根据 ClientId 和订阅名自动生成不需要手动DEFINE QLOCAL但 ClientId 必须在连接工厂里配好。检查文档有没有把 ClientId 和订阅的对应关系写清楚。4.3 用 MQSC 脚本做一次干跑文档里会附带 MQSC 创建脚本。在真正执行前可以先在测试环境的队列管理器上跑一遍看有没有语法错误。# 假设队列管理器叫 QM_JEESAMPLES脚本叫 create-all.mqsc runmqsc QM_JEESAMPLES create-all.mqsc # 执行后检查对象是否创建成功 echo DISPLAY QLOCAL(*) | runmqsc QM_JEESAMPLES | grep -c QUEUE( echo DISPLAY TOPIC(*) | runmqsc QM_JEESAMPLES | grep -c TOPIC( echo DISPLAY CHANNEL(*) | runmqsc QM_JEESAMPLES | grep -c CHANNEL(如果队列数、主题数、通道数和文档里的清单对得上说明脚本可用。对不上就回去看是哪条DEFINE失败了runmqsc会打印错误行号。4.4 验证应用能否连上对象建好后把应用的 JNDI 配置指向 IBM MQ启动应用。观察日志里有没有JMSConnectionFactory相关的报错。如果应用能正常启动、消息能发能收说明整条链路通了。# 在 Open Liberty 里检查 JMS 相关配置是否加载 grep -i jms\|mq ${SERVER_LOG}/messages.log | tail -50看到CWSJY0003I这类 JMS 资源绑定成功的日志基本就没问题了。5. 本篇常见错排查5.1 Agent 把队列管理器拆多了这是最常见的坑。第一次分析时Agent 容易按模块隔离的思路把点对点队列放一个队列管理器、发布订阅主题放另一个甚至每个示例模块一个。理由是避免消息干扰。实际上 IBM MQ 单个队列管理器同时支持两种消息模型MDB 通过destinationLookup精确绑定到特定目的地不会误消费其他队列的消息。队列物理名称各不相同天然隔离。除非你有明确的多租户安全隔离需求否则一个队列管理器就够。排查方法看文档里队列管理器数量。如果超过 1 个问 Agent为什么不能合并成一个让它给出具体的技术理由。如果理由只是避免干扰而没有实际冲突证据就让它重写。5.2 漏掉注解定义的 JMS 对象JMSDestinationDefinition和JMSConnectionFactoryDefinition写在 Java 类上不在 XML 里。如果 Agent 的搜索策略偏向配置文件就会漏掉这些。排查方法在项目里跑一次grep -rn JMSDestinationDefinition\|JMSConnectionFactoryDefinition --include*.java数一下有多少处。然后看文档里有没有对应数量的对象。对不上就是漏了。5.3 JNDI 名称和物理名称混淆Jakarta EE 里 JNDI 名称是逻辑名比如java:module/jms/newsTopicIBM MQ 里需要的是物理名比如PhysicalNewsTopic。两者必须建立映射否则应用找不到队列。排查方法检查文档里的映射表每一行 JNDI 名称都要有对应的物理名称。如果某个 JNDI 名称后面是空的说明 Agent 没找到物理名需要你手动补或者让它再读一遍相关文件。5.4 持久订阅的 ClientId 冲突两个模块用了同一个 ClientId 但订阅名不同在 MQ 上会报冲突。比如durablesubscriptionexample和shared/shareddurableconsumer都用了MyID。排查方法把文档里所有持久订阅的 ClientId 列出来看有没有重复。如果有确认这两个模块是否会同时运行。如果不会同时运行可以共用如果会就得改其中一个的 ClientId。5.5 通道认证没关导致连接被拒开发环境里IBM MQ 默认的通道认证会拦截 JMS 客户端连接报MQRC 2035或MQRC 2059。文档里的 MQSC 脚本通常会带ALTER QMGR CHLAUTH(DISABLED)但如果漏了连接就会失败。排查方法连接报错时先在 MQ 上执行DISPLAY QMGR CHLAUTH看是不是ENABLED。是的话临时关掉ALTER QMGR CHLAUTH(DISABLED)。生产环境不要这么干要用精细的通道认证规则。5.6 事务模式配错导致消息重复或丢失SESSION_TRANSACTED的模块如果配成了AUTO_ACKNOWLEDGE消息可能在处理失败时被确认导致丢失。反过来非事务模块配成事务模式可能因为忘记 commit 导致消息一直不发出。排查方法对照文档里的事务模式表逐个模块核对代码里的createSession或createContext参数。transactedexample这类涉及订单确认的模块必须是SESSION_TRANSACTED。6. 把清单变成迁移的起点盘清楚 MQ 对象只是迁移的第一步但这一步做扎实了后面的 JNDI 重配、连接工厂切换、MDB 重新部署才有依据。我试过在几个模块的项目上跑这套流程从启动 Claude Code 到拿到可执行的 MQSC 脚本大概二十分钟比人工翻代码快得多而且不容易漏。如果你在验证阶段发现模型对某个模块的 JMS 对象提取不准可以单独把那个模块的代码贴进模型对话里让它重新分析https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入过程中如果遇到 Key 配置、base URL 报错这类问题接入文档里有详细的参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content对于需要长期跑迁移任务、频繁调用 Agent 做代码分析的团队Coding Plan 按周期计费会比按量调用更划算适合把 Claude Code 当成日常迁移工具来用的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后留一个实操建议把生成的docs/ibm-mq-migration-analysis.md提交进仓库作为迁移基线。后面每改一处 JMS 配置就重新跑一次分析用git diff看清单变化。这样 MQ 对象清单始终和代码同步不会出现代码改了但 MQ 没建的断层。
