KSP2 中模块名包含连字符导致的 IllegalArgumentException 问题解析

问题背景

在 Kotlin Symbol Processing (KSP) 2.1.20-2.0.0 版本中，开发者遇到了一个关于模块命名的限制问题。当使用 KSP 处理包含连字符("-")的模块名称时，系统会抛出 IllegalArgumentException 异常，提示"not a valid name"。

问题表现

具体错误表现为当模块名称中包含连字符时，例如"database-test"，KSP 处理器会生成类似"DatabaseTestModule_ProvidesNeotasteDatabase$database-test_debugFactory"的合成类名，这种包含特殊字符的命名方式会导致 Java 虚拟机无法识别，从而抛出异常。

技术原理

这个问题本质上与 Java 和 Kotlin 的标识符命名规范有关：

1. Java 虚拟机规范中，类名和方法名只能包含字母、数字、下划线和美元符号
2. 连字符("-")在 JVM 标识符中是不合法的字符
3. KSP 在生成代码时会直接使用模块名作为生成类名的一部分
4. 当模块名包含连字符时，生成的类名就违反了 JVM 规范

解决方案

针对这个问题，开发者可以采取以下解决方案：

1. 避免使用连字符：最简单的解决方案是重命名模块，使用下划线("_")或驼峰式命名代替连字符
2. 升级 KSP 版本：这个问题在 KSP 2.1.20-2.0.1 版本中已经得到修复
3. 自定义命名策略：对于高级用户，可以通过自定义 KSP 处理器来修改生成的类名格式

最佳实践

为了避免类似问题，建议开发者遵循以下命名规范：

1. 模块名使用驼峰式命名法（如 databaseTest）
2. 或者使用下划线连接（如 database_test）
3. 避免在标识符中使用任何特殊字符
4. 保持命名一致性，遵循项目已有的命名约定

总结

KSP 作为 Kotlin 的符号处理工具，在代码生成过程中需要严格遵守 JVM 的命名规范。这个问题的出现提醒我们在项目命名时需要考虑到工具链的限制，特别是在跨语言开发环境中。随着 KSP 的持续更新，这类边界情况问题正在被逐步解决，开发者只需保持工具链更新并遵循最佳实践即可避免大部分问题。