Chat2DB 社区版 Java 服务端接口契约规范领域驱动下的分层、命名与边界约束【免费下载链接】Chat2DBChat2DB is a free, cross-platform, local-first database client and SQL workspace for developers, DBAs, analysts, and data teams. Connect to 40 databases, manage data, edit and run SQL, and use your own AI model to generate, explain, and optimize queries. Available on desktop, web, Docker, and CLI, with MCP support.项目地址: https://gitcode.com/GitHub_Trending/ch/Chat2DB导读本文基于 spec/code/server/java-interface-contracts.md 整理系统讲解 Chat2DB 社区版服务端chat2db-community-server如何通过接口契约约束模块协作从I前缀命名、业务域前缀体系到domain-api/domain-core/spi/plugins/web各模块的职责边界再到请求/响应对象命名、枚举处理与 Bean Validation 校验规范。读完本文你将掌握一套可直接套用的 Java 服务端接口设计纪律并能在 Chat2DB 仓库中快速定位契约定义、实现与控制器三者的对应关系。1. 核心原则模块只通过接口与领域模型协作Chat2DB 社区版服务端Maven 多模块工程根模块见 chat2db-community-server/pom.xml的基本协作规则是服务端模块之间只能通过接口和领域模型协作调用方不得绕过接口直接依赖某个实现类接口契约必须保持稳定、可替换、可评审不得把 Web、持久化、插件实现细节泄漏到上层模块。这意味着业务代码看到的是做什么的抽象而不是怎么做的具体类。实现细节被隔离在各自的模块中从而让上层模块尤其是 Web 层对底层技术选型无感知。2. 接口命名I前缀 业务域前缀所有 Java 接口统一使用I前缀命名并按职责进一步细分接口类型命名模式示例业务服务接口IXxxServiceIDbDataSourceService、IAiChatHistoryService存储能力接口IXxxStorage/IXxxRepository或更具体的能力名存储契约插件扩展接口能力后缀如IXxxManager、IXxxDialect、IXxxPlugin、IXxxProcessorIDbMetaData、ISQLDialect、IPlugin内部回调/监听/策略接口同样以I开头IProgressListener、IExportStrategy文档给出的最小示例public interface IDataSourceService { } public class DataSourceServiceImpl implements IDataSourceService { }业务服务接口必须包含业务域前缀命名模板为IDomainObjectService IDomainObjectCapabilityService允许的顶层业务域前缀如下前缀含义Sys系统设置、账号、权限、OAuth、代理与运行时配置Db数据库连接、元数据、SQL、DDL/DML、表、视图、函数、存储过程、触发器以及 Redis 数据操作AiAI 对话、模型、补全completion、RAG、embedding 与 AI 辅助 schema 能力CliCLI 与无头headless能力McpMCP 协议、工具、资源与授权Task导入导出、异步任务与长时运行工作流Ops操作历史、审计、保存的查询与历史记录Plugin插件扩展能力特别注意Rdb、Redis、Database、DataSource、Table、View、Function、Procedure、Trigger都不是顶层域它们属于Db域。这在仓库中有大量实例佐证例如 IDbDataSourceService.java、IDbTableService、IDbSqlExecutionService、IDbDmlExecutionService等均以Db开头且按业务子包db、ai、cli、ops、sys、mcp组织在domain/api/service下。3. 接口归属每个契约都有唯一的家接口契约必须定义在正确的模块中防止职责漂移契约类型所属模块说明应用业务能力契约chat2db-community-domain-api数据源、SQL、任务、工作区、AI 配置等业务契约业务能力实现chat2db-community-domain-core实现 domain-api 中定义的接口存储契约chat2db-community-domain-api只定义存储能力与领域模型存储实现chat2db-community-storage实现 domain-api 的存储接口数据库插件扩展点chat2db-community-spi驱动、元数据、DDL、Redis 操作等扩展点数据库插件实现chat2db-community-plugins/*实现 SPI 接口HTTP 入口chat2db-community-webController、请求/响应 DTO、转换器、适配器与 Web 门面横切支撑chat2db-community-tools共享工具、异常与运行时辅助不承载业务契约domain-api只定义业务契约、契约模型与契约枚举。不得在其中加入exception、util等支撑包也不得把*Exception类型藏在model等业务包下。共享异常与工具统一放在chat2db-community-tools例如ai.chat2db.community.tools.exception与ai.chat2db.community.tools.util。仓库实证domain-api共约 437 个 Java 文件全部以ai.chat2db.community.domain.api.*为根模型集中在model/request、model/response、model/datasource、model/metadata等业务包下未见exception/util支撑包而通用分页参数PageQueryParam、OrderBy等确实来自ai.chat2db.community.tools.wrapper.param见 DbDataSourcePageQueryRequest.java 的 import 语句与文档描述完全吻合。4. 禁止直接依赖实现类契约纪律不仅约束命名更约束依赖方向。以下行为被明确禁止调用方只注入接口不得注入XxxImpl类web只依赖domain-api接口不依赖domain-core实现任何模块不得 import 另一个模块的impl包或XxxImpl类不得用ApplicationContext.getBean(Impl.class)绕过接口不得通过反射、类名字符串或 bean 名称直接定位实现类调用方不得用new直接实例化业务实现。允许的例外启动装配模块可以装配实现模块但不得包含业务调用逻辑实现模块内部可以持有私有辅助类、转换器与策略但这些类型不得成为跨模块契约。从源码结构看domain-core的实现集中在ai.chat2db.community.domain.core.impl.*包下如impl/db/DbDataSourceServiceImpl.java、impl/ai/AiChatHistoryServiceImpl.java、impl/cli/CliSqlServiceImpl.java等且类名与接口一一对应IDbDataSourceService→DbDataSourceServiceImpl这正是实现类必须显式implements IXxxService这一规则的落地形态。5. Service 规则与 Web Controller 规则5.1 Service 规则承担业务服务职责的类必须先有接口服务接口属于domain-api服务实现属于domain-core实现类命名为XxxServiceImpl并显式声明implements IXxxServiceweb模块不得新增业务服务只能包含 HTTP 适配器、DTO 转换器与 Web 门面重命名包或类不会改变其职责业务编排始终属于domain-core。5.2 Web Controller 规则Controller 名称必须包含顶层业务域前缀之一Sys、Db、Ai、Cli、Mcp、Task、Ops或PluginController 文件名必须与public class名称完全一致数据库相关 Controller 属于Db域例如DbTableController、DbDmlController、DbRedisKeyControllerRdb、Redis、Database、DataSource、Table、View、Function、Procedure、Trigger不得作为顶层 Controller 域前缀。仓库实证在 chat2db-community-web 的控制器目录中可以看到DbDataSourceController.java、DbTableController.java、DbSqlController.java、DbRedisKeyController.java、SysSystemController.java、McpConfigController.java、CliSqlController.java、TaskController.java、OpsOperationLogController.java等命名与文件一致性完全符合该规范且没有出现以Rdb、Table等开头的控制器。6. 接口参数与返回值契约对象的命名纪律接口签名必须表达完整业务语义禁止把接口当数据传输的垃圾桶能直接暴露清晰业务参数的直接暴露不要为了减少参数个数而创建只有字段的XxxRequest壳当参数具有复合语义、校验语义或跨层复用价值时才使用请求对象接口输入对象命名XxxRequest禁止使用XxxParam、XxxCommand、XxxQuery、XxxDTO、XxxVO接口输出对象命名XxxResponse禁止使用XxxResult、XxxDTO、XxxVOXxxRequest参数名使用对应的小驼峰形式例如TableQueryRequest tableQueryRequest、CreateDataSourceRequest createDataSourceRequest避免param、queryParam、request这类泛化命名请求对象必须表达完整业务语义形式为DomainObjectActionRequest动作响应对象使用DomainObjectActionResponse资源视图或领域输出模型可使用DomainObjectResponse但仍需业务域前缀CRUD 契约按域-对象-动作顺序命名DbDatasourceCreateRequest/DbDatasourceCreateResponseDbDatasourceUpdateRequest/DbDatasourceUpdateResponseDbDatasourceDeleteRequest/DbDatasourceDeleteResponseDbDatasourceGetRequest/DbDatasourceGetResponseDbDatasourceListRequest/DbDatasourceListResponse非 CRUD 契约使用真实业务动作例如DbSqlExecuteRequest、DbConnectionTestRequest、AiChatSendRequest、TaskImportStartRequest同一方法的 Request、Response、Service、ServiceImpl 名称必须暴露相同的DomainObjectAction语义锚点简单值可以直接返回void、JDK 基本类型及包装类、String、Long、集合或分页模型接口不得返回通用结果包装如ActionResult、ResultT、DataResultT、ListResultT、PageResultT、WebPageResultT或 HTTP 包装结构化业务输出必须使用具体的XxxResponse而不是成功/消息/数据通用包装领域接口不得返回 Web 请求、Web 响应、VO 或 HTTP 结果包装领域接口不得暴露 Servlet / Spring MVC 类型、MyBatis mapper 或实体、网关 DTO、本地文件存储实现。文档给出的示范接口public interface IDbDatasourceService { DbDatasourceCreateResponse create(DbDatasourceCreateRequest dbDatasourceCreateRequest); void delete(DbDatasourceDeleteRequest dbDatasourceDeleteRequest); DbDatasourceGetResponse get(DbDatasourceGetRequest dbDatasourceGetRequest); }仓库实证真实的 IDbDataSourceService.java 使用preConnect(DbDataSourcePreConnectRequest dbDataSourcePreConnectRequest)、connect(Long id)、close(Long id)、defaultDriverConfig(String dbType)、testSshConnection(SSHInfo ssh)等签名——参数名与类型一一对应简单参数直接使用Long/String复合参数使用语义化的XxxRequest在model/request/datasource下可以看到DbDataSourcePreConnectRequest.java、DbDataSourceTestRequest.java、DbDataSourcePageQueryRequest.java、DbDataSourcePositionUpdateRequest.java、DbDataSourceCloseRequest.java等全部遵循DomainObjectActionRequest命名。6.1 枚举类型处理接口是稳定的契约因此接口方法参数、返回值与契约对象字段不得暴露 Javaenum类型枚举属于实现细节契约对外暴露其实际值例如String type、String status、Integer code枚举通过getCode()、code()、name()等方法对外提供值值到枚举的解析统一放在静态枚举方法中如from(String value)或from(Integer value)不要把valueOf、switch、try-catch解析逻辑散落在 service、builder、adapter 或 controller 中Web 层在转换 HTTP DTO 与领域契约对象时只能调用枚举自身的转换方法。7. 接口参数校验声明式 Bean Validation请求对象使用 Bean Validation 注解做基础校验优先使用NotNull、NotBlank、NotEmpty、Size、Min、Max、Pattern、Valid嵌套对象或集合元素需要继续校验时使用Valid校验由 Controller、门面或其他调用入口触发实现类不得重复校验注解已表达的基础空值、长度、格式检查权限、状态流转、对象存在性、业务冲突等仍属于 domain-core 的业务规则不靠注解表达。仓库实证DbDataSourcePageQueryRequest.java 中对searchKey声明了Size(max 256)SPI 层接口IDbMetaData的viewNames(...)方法对databaseName参数声明了NotEmpty见 IDbMetaData.java。这印证了契约对象声明基础校验、实现不重复检查的规范。8. SPI 与 Domain API 的边界domain-api定义应用业务能力spi定义数据库插件扩展能力业务服务不属于spi插件扩展点不属于domain-apidomain-core可以通过spi使用插件能力但不得依赖具体插件实现。仓库实证spi模块chat2db-community-spi中的接口全部是插件能力型命名IPlugin、IDbMetaData、ISQLDialect、IDbManager、ICommandExecutor、IKeyOperations、IRoutineManager、ISqlCompletionProvider等而domain-api下的接口则全部是业务服务型命名IDbDataSourceService、IAiChatHistoryService、IMcpConfigService、ICliSqlService、IOpsOperationSavedService等两类接口泾渭分明。domain-core的impl/db/DbSqlExecutionServiceImpl.java、impl/db/DbTableServiceImpl.java等实现则通过 SPI 编排各数据库方言能力。9. 模块包结构分类包的唯一性约束为保持包结构可预测规范还约束了模块内部的包布局在每个 Maven 模块中enums、constant、model、config是模块级分类包这些包可以包含业务子包例如enums/completion、model/completion/context、config/completion不得把分类包放在业务包之下例如completion/enums、completion/model、completion/config、impl/rdb/doc/constant都是禁止的使用单数包名constant不要出现constants包一个分类包在整个模块中只出现一次且必须是模块根包之后的第一个段后续业务子包不得复用enums、constant、model、config这些名字现有的request、response、dto、service、impl、converter、adapter包不在此分类规则内源码包与目录不得使用rdb数据库相关源码包统一使用db兼容性的 URL 如/api/rdb/...不在此包规则范围内。规范示例ai.chat2db.plugin.mysql.enums.completion ai.chat2db.plugin.mysql.model.completion.context ai.chat2db.plugin.mysql.config.completion ai.chat2db.community.domain.core.constant.db.doc仓库实证MySQL 插件chat2db-community-mysql的包结构即为completion/catalog、completion/resolver、completion/slot、completion/analysis、completion/evidence等业务包分类包enums/model/config只在模块根级别出现一次同时数据库相关业务包统一为db如domain/api/service/db、domain/core/impl/db并未使用rdb命名。10. 评审清单接口契约如何被审查文档为接口契约评审提供了 17 项可直接执行的检查清单是 Code Review 时的对照表src/main/java下每个接口都使用I前缀domain-api 服务接口同时具备I前缀与允许的顶层业务域前缀domain-core 中每个*ServiceImpl都显式 implements 某个接口web 模块没有新增业务service包或业务*Service.java类型Web 控制器使用业务域前缀且文件名与 public class 名一致源码包、目录与 Java 标识符不保留过时的rdb/Rdb命名模块不 import 其他模块的impl包或*Impl类代码不通过ApplicationContext.getBean(XxxImpl.class)直接获取实现domain-api 与 SPI 签名使用XxxRequest/XxxResponse契约对象domain-api 与 SPI 接口不返回通用结果包装domain-api 与 SPI 中XxxRequest参数使用匹配的小驼峰参数名请求对象至少声明一个适用的基础校验注解domain-api 与 SPI 的签名和契约字段不暴露 Java 枚举类型值到枚举的解析不散落在枚举类型之外enums、constant、model、config遵循模块级分类包规则domain-api 的 request / response 包下的契约类型使用允许的顶层业务域前缀domain-api 不保留exception/util支撑包、*Exception类型或过时的包引用。文档同时明确第三方包与 Spring Bean 初始化顺序不在此清单范围内。11. 如何在仓库中继续深入如果想把这套规范对照到真实代码推荐按以下路径阅读契约定义chat2db-community-domain-api 下的service/db、service/ai、service/sys、service/cli、service/mcp、service/ops各子包契约模型同模块下 model/request 的datasource、sql、ai、cli、operation、runtime等子包实现对照chat2db-community-domain-core 下的impl/db、impl/ai、impl/sys、impl/cli、impl/operation等插件扩展点chat2db-community-spi 根包下的IPlugin、IDbMetaData、ISQLDialect、ISqlCompletionProvider等插件实现chat2db-community-plugins 下各数据库模块如 MySQL、PostgreSQL、Oracle、Redis 等HTTP 入口chat2db-community-web 下的各 Controller。结语接口契约是 Chat2DB 社区版服务端能够支撑 40 数据库插件、多端入口Web/CLI/MCP而保持结构清晰的基石I前缀让接口一目了然业务域前缀让契约归属明确domain-api/spi双契约体系让业务能力与插件能力各安其位请求/响应命名与校验规则让跨层协作可预测、可评审。对于任何追求模块边界清晰、实现可替换的 Java 服务端项目这套规范都值得直接借鉴。【免费下载链接】Chat2DBChat2DB is a free, cross-platform, local-first database client and SQL workspace for developers, DBAs, analysts, and data teams. Connect to 40 databases, manage data, edit and run SQL, and use your own AI model to generate, explain, and optimize queries. Available on desktop, web, Docker, and CLI, with MCP support.项目地址: https://gitcode.com/GitHub_Trending/ch/Chat2DB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考