MyBatis/iBATIS Mapper

VS Code / Cursor 扩展：为 MyBatis、iBATIS 的 Mapper XML 与 Java 提供跳转、补全、悬停等语言服务。

主要意图

在编辑器中建立 Mapper XML ↔ Java 的关联，使开发者可以：

在 XML 的 <select id="xxx"> 上跳转到调用该 statement 的 Java 代码
在 Java 的 "xxx" 或 SQL_PREFIX + "xxx" 上跳转到对应 XML 中的定义
在 Java 中按前缀补全 statement id（含 namespace）
悬停查看 resultType、resultMap、SQL 预览等

支持 <mapper namespace="">（MyBatis）与 <sqlMap namespace="">（iBATIS），不依赖外部 XML 库，使用正则解析。

功能特性

能力	说明
转到定义	XML statement → Java 引用；Java statement id → XML 定义
转到类型定义	Java statement id → XML 定义
补全	Java 内按前缀补全完整 id（含 namespace）与本地 id
悬停	展示 namespace、resultType/resultMap、SQL 预览（约 100 字）
重载索引	命令「MyBatis: Reload Mapper Index」全量重建索引

本扩展不提供「转到实现」「查找引用」，以避免覆盖 Java 语言服务的接口实现/引用跳转。

架构说明

┌─────────────────┐     IPC      ┌─────────────────────────────────────────┐
│  VS Code 主机   │◄────────────►│  LSP Server（Node 子进程）               │
│  client/        │              │  server/                                 │
│  - extension.ts │              │  - server.ts  入口、Definition/Completion│
│  - documentSelector(java+xml)  │  - indexBuilder 扫描 XML + 收集 Java 引用│
│  - 文件监视、reload 命令       │  - mapperIndex  byFqId/byLocalId 解析    │
└─────────────────┘              │  - xmlParser  解析 XML 无外部库         │
                                 └─────────────────────────────────────────┘

客户端：注册 LSP 客户端，documentSelector 匹配 Java 与 Mapper XML 模式；将工作区目录通过 initializationOptions.workspaceFolders 传给服务端；监听 XML 变更并支持手动重载索引。
服务端：启动时及打开 XML/Java 时触发 rebuildIndex；对工作区根与已打开文档所在项目根做磁盘扫描（glob *_sql.xml、*Mapper.xml 等），解析 XML 得到 statement 列表，扫描 Java 得到 statement id → 位置；合并为 MapperIndex（byFqId、byLocalId、javaRefs），供 Definition/TypeDefinition/Completion/Hover 查询。

目录说明

路径	说明
`client/extension.ts`	扩展入口：创建 LSP 客户端、documentSelector、文件监视、注册命令 `mybatis.reloadIndex`
`server/server.ts`	LSP 主逻辑：初始化、ensureRootPaths、rebuildIndex、onDefinition/onTypeDefinition/onCompletion/onHover、DidChangeWatchedFiles、extractStatementsFromContent 等
`server/xmlParser.ts`	解析 Mapper XML：`<mapper>`/`<sqlMap>` namespace、`<select\|insert\|update\|delete>` id/resultType/resultMap、typeAlias、SQL 预览
`server/indexBuilder.ts`	`buildIndex`：按 glob 扫描根目录收集 XML，解析后得到 byUri；`buildJavaRefs`：扫描 Java，收集 statement id → RefLocation；glob 与路径规范化
`server/mapperIndex.ts`	`buildMapperIndex(byUri, javaRefs)` 构建 byFqId/byLocalId；`resolveStatementId` 按完整 id 或本地 id 解析位置
`server/javaUtils.ts`	Java 侧工具：getStringLiterals、getMethodNameRanges、isLikelyStatementId、resolveStatementIdFromLine、getPrefixConstants 等
`server/types.ts`	类型定义：StatementLocation、XmlMapperIndex、MapperIndex、RefLocation

产物与配置：

client/out/、server/out/：编译输出（勿提交，见 .gitignore）
.vscode/launch.json、tasks.json：本地调试与编译任务
DEBUG.md：调试说明

配置与命令

mybatisMapper.mapperXmlPatterns：Mapper XML 的 glob 列表，默认包含 **/*_sql.xml、**/*Mapper.xml 等。
mybatisMapper.indexMaxFiles：参与索引的 XML 数量上限，默认 5000。

命令：MyBatis: Reload Mapper Index — 全量重建 Mapper 索引。

安装 VSIX 后：在扩展列表中找到「MyBatis/iBATIS Mapper」，若条目没有勾选表示未启用，需点击该扩展，在详情中点击 「启用」/「Enable」（或右键选择启用），然后重新加载窗口。

查看日志：底部 Output 面板右侧下拉选择 「MyBatis Mapper」，可看到扩展与语言服务端日志。

开发与构建

环境：Node.js、npm；VS Code 1.85+。

npm install
npm run compile          # 编译 client + server
npm run package          # 编译后打包为 .vsix（prepackage 会先 compile）

本地调试：F5 启动扩展开发主机（依赖 .vscode/launch.json 与 tasks.json），详见 DEBUG.md。

发布到扩展市场

创建发布者（若尚未有）：打开 VS Code 市场管理，用 Microsoft 账号登录，新建 Publisher（如 limingzi），与 package.json 中 publisher 一致。
获取令牌：同一站点 → Personal Access Tokens → 新建，权限勾选 Marketplace (Publish)，复制令牌。

登录并发布：

npx @vscode/vsce login limingzi    # 按提示粘贴令牌，仅首次需要
npm run package                 # 生成 .vsix
npx @vscode/vsce publish        # 发布当前版本到 marketplace.visualstudio.com

后续更新：改 package.json 的 version（如 0.1.1）后再次执行 npx @vscode/vsce publish。

图标：根目录 icon.png（扩展列表与市场展示用，建议 128×128 或 256×256 PNG）。

开发者与仓库

作者：李明梓（mingzi.li@lkcoffee.com）
协议：见仓库内 LICENSE