1. 为什么在EOS7.5里还要手写接口EOS7.5这套低代码开发平台很多团队用久了会形成一种惯性——能拖拽就拖拽能配置就配置实在不行才写代码。这个思路本身没错低代码平台的价值就在于把重复劳动压缩掉。但问题出在一旦业务逻辑稍微复杂一点比如涉及多表联动、跨服务调用、复杂事务控制纯靠平台自带的可视化编排就会变得非常别扭。我见过不少项目前期为了赶进度全用拖拽实现后期需求一变改一个逻辑要翻七八个配置页面维护成本反而比手写代码高出一大截。这就是为什么在EOS7.5里手写接口依然是一项必须掌握的硬技能。所谓手写接口指的是不依赖平台的可视化逻辑编排器而是直接在代码层面定义服务接口、实现业务逻辑、管理事务边界。它和低代码不是对立关系而是互补关系——简单CRUD交给平台复杂业务逻辑用手写接口兜底。三层架构在这里扮演的角色是让手写接口不至于变成一锅粥。表现层负责接收请求和返回结果业务逻辑层负责处理核心规则数据访问层负责和数据库打交道。每一层只做自己该做的事层与层之间通过接口通信而不是直接依赖具体实现。这套思想说了几十年了但在EOS7.5这种低代码平台上很多人反而容易忽略它因为平台本身提供了大量“捷径”让你不知不觉就把业务逻辑写到了表现层或者数据访问层里。这篇文章适合两类人看一类是刚接触EOS7.5、对平台开发模式还不太熟悉的开发者另一类是用了一段时间平台、发现可视化编排越来越力不从心的老手。我会从实际项目出发把三层架构在EOS7.5手写接口中的落地方式拆开讲清楚包括目录结构怎么设计、接口怎么定义、事务怎么控制、异常怎么处理以及那些只有踩过坑才知道的细节。2. 三层架构在EOS7.5手写接口中的具体落地方式2.1 表现层只做参数校验和结果封装表现层在EOS7.5里通常对应的是服务入口也就是外部系统或前端页面调用的那个接口。很多人在这一步就犯了错误——把业务判断写在了表现层。比如“用户余额是否充足”“订单状态是否允许取消”这类逻辑本质上属于业务规则不应该出现在表现层。表现层该做的事只有三件接收参数、做基础格式校验、调用业务逻辑层并封装返回结果。基础格式校验指的是参数是否为空、类型是否正确、长度是否超限而不是业务规则校验。举个例子传入的订单ID不能为空这是格式校验传入的订单ID对应的订单是否存在、是否属于当前用户这是业务校验应该放在业务逻辑层。在EOS7.5中表现层的实现通常是一个实现了特定接口的类或者是一个带有注解的方法。我习惯的做法是表现层方法体控制在十行以内超过十行就说明有逻辑该往下沉了。返回结果统一用平台提供的响应对象封装包含状态码、消息和数据体不要直接返回实体对象或者Map否则前端处理起来会很混乱。2.2 业务逻辑层核心规则的唯一归属地业务逻辑层是整个三层架构的心脏。所有业务规则、计算逻辑、流程判断都应该集中在这一层。它的设计原则是不关心数据从哪来、到哪去只关心业务规则本身是否正确执行。在EOS7.5中手写业务逻辑层我建议按业务模块划分包结构而不是按技术分层划分。比如订单相关的所有业务逻辑放在一个包里用户相关的放在另一个包里。每个业务类实现一个对应的接口接口定义在单独的API模块中这样表现层依赖接口而不是实现类方便后续替换或扩展。业务逻辑层调用数据访问层时应该通过数据访问接口来调用而不是直接依赖具体的DAO实现。这样做的好处是当数据源发生变化时比如从单库变成分库分表只需要替换数据访问层的实现业务逻辑层完全不用动。2.3 数据访问层屏蔽数据库差异数据访问层的职责很纯粹执行SQL、映射结果集、返回实体对象。它不应该包含任何业务判断也不应该处理事务——事务的边界应该由业务逻辑层来控制。在EOS7.5中数据访问层可以用平台提供的ORM框架也可以手写SQL。我的建议是简单查询用ORM复杂查询手写SQL。因为ORM在处理多表关联、聚合查询时往往力不从心强行用ORM反而会让代码变得难以理解。手写SQL的时候把SQL语句放在独立的配置文件中不要硬编码在Java代码里这样后续调整SQL不需要重新编译。2.4 三层之间的依赖关系与数据传递三层架构的关键在于依赖方向表现层依赖业务逻辑层业务逻辑层依赖数据访问层反过来不行。数据传递方面层与层之间传递的是数据传输对象而不是数据库实体。数据库实体只存在于数据访问层和业务逻辑层之间表现层不应该直接接触到数据库实体。这样做的好处是当数据库表结构发生变化时只需要调整数据访问层和实体映射表现层和业务逻辑层的接口不受影响。很多项目后期维护困难就是因为数据库实体在整个系统中到处传递改一个字段要翻遍所有代码。3. 手写接口时最容易踩的五个坑3.1 事务边界划在了错误的位置这是我在实际项目中最常见的问题。很多开发者习惯在数据访问层的方法上加事务注解觉得这样“粒度细、控制精准”。但实际上一个业务操作往往需要调用多个数据访问方法如果事务加在数据访问层每个方法各自独立事务业务逻辑层就没法保证整体的一致性。正确的做法是把事务边界划在业务逻辑层的方法上。一个业务方法对应一个完整的事务方法内的所有数据访问操作要么全部成功要么全部回滚。在EOS7.5中可以通过平台提供的事务注解或者编程式事务来实现。我倾向于用编程式事务因为这样事务的边界在代码里一目了然不需要去猜注解的传播行为。3.2 异常被吞掉导致事务不回滚这个问题比第一个更隐蔽。默认情况下只有运行时异常才会触发事务回滚受检异常不会。很多开发者习惯把异常捕获后包装成受检异常往上抛结果事务根本不回滚数据出现不一致。解决办法有两个一是在事务注解中明确指定哪些异常触发回滚二是统一使用运行时异常来传递错误。我个人的做法是定义一个业务异常基类继承自运行时异常所有业务错误都抛这个异常。这样既保证了事务回滚又能在表现层统一捕获处理。3.3 表现层直接调用数据访问层这种情况通常发生在赶进度的时候。表现层需要查一个列表开发者觉得“就一个查询没必要再写一个业务方法”于是直接调用了数据访问层。一次两次没关系但一旦开了这个口子后面就会越来越多最终三层架构名存实亡。我的经验是在代码审查阶段就要严格把关发现表现层直接调用数据访问层就打回去重写。哪怕业务逻辑层的方法只是简单转发也要保留这一层因为后续这个查询很可能需要加缓存、加权限过滤、加数据脱敏到时候再补业务逻辑层就来不及了。3.4 接口定义过于具体导致无法复用有些开发者定义接口时方法名和参数都跟具体业务场景绑死比如getOrderDetailForPage、getOrderDetailForExport。这样定义接口后续再有新的场景需要查询订单详情又得加一个新方法接口越来越臃肿。更好的做法是按业务能力定义接口而不是按调用场景。比如getOrderDetail就是获取订单详情至于调用方是页面还是导出那是调用方的事。如果不同场景需要的数据字段不同可以通过参数控制返回字段或者定义多个粒度的接口但命名要体现业务含义而不是技术场景。3.5 忽略接口的版本管理EOS7.5的项目往往需要对接多个外部系统接口一旦发布就不能随意修改否则会影响调用方。但业务需求是不断变化的接口也需要迭代。如果没有版本管理机制每次修改接口都要通知所有调用方同步更新协调成本极高。我的做法是在接口路径中带上版本号比如/api/v1/order/detail和/api/v2/order/detail。新版本接口上线后旧版本继续维护一段时间给调用方留出迁移窗口。在EOS7.5中可以通过配置路由规则来实现多版本共存。4. 从零搭建一个符合三层架构的手写接口4.1 项目目录结构设计在EOS7.5中创建手写接口项目时目录结构应该清晰体现三层架构。我通常按以下方式组织api模块存放所有接口定义包括表现层接口和业务逻辑层接口。这个模块不包含任何实现代码只包含接口和传输对象。service模块存放业务逻辑层的实现类。依赖api模块和dao模块。dao模块存放数据访问层的实现类。依赖api模块中的实体定义。web模块存放表现层的实现类。依赖api模块和service模块。这种模块划分方式的好处是编译期就能发现依赖违规。比如dao模块如果试图引用service模块的类编译就会失败从机制上保证了依赖方向的正确性。4.2 定义业务接口与传输对象先定义传输对象。传输对象是层与层之间传递数据的载体它和数据库实体是两回事。数据库实体描述的是表结构传输对象描述的是业务数据。比如订单实体可能包含创建时间、修改时间、删除标记这些技术字段但传输对象只包含业务需要的字段。定义传输对象时我习惯用不可变对象也就是所有字段在构造时设置之后不再修改。这样做的好处是线程安全而且避免了在传递过程中被意外修改。在EOS7.5中可以用平台提供的DTO基类也可以自己写简单的POJO。业务接口的定义要遵循单一职责原则。一个接口只负责一个业务能力比如订单查询接口、订单创建接口、订单取消接口分开定义而不是把所有订单相关操作塞进一个接口。这样接口的调用方可以按需依赖不会被迫依赖不需要的方法。4.3 业务逻辑层的实现要点业务逻辑层的实现类应该只包含业务规则不包含技术细节。比如计算订单折扣业务逻辑层只负责根据用户等级、商品类型、促销活动计算出最终价格至于这个价格怎么持久化、怎么返回给前端那是其他层的事。在实现业务方法时我习惯先做参数校验再做业务规则校验最后执行核心逻辑。参数校验检查的是参数本身是否合法比如金额不能为负数业务规则校验检查的是当前业务状态下是否允许执行该操作比如已取消的订单不能再次取消。这两类校验分开写代码可读性会好很多。事务控制方面我通常在业务方法入口处开启事务方法正常返回时提交抛出异常时回滚。在EOS7.5中可以用平台的事务模板来简化代码。需要注意的是事务方法内不要做远程调用或者耗时操作否则事务会持有数据库连接很长时间影响系统吞吐量。4.4 数据访问层的SQL组织方式数据访问层的SQL我建议放在独立的XML文件中而不是用注解写在代码里。XML文件的好处是格式清晰、便于维护而且修改SQL不需要重新编译Java代码。在EOS7.5中可以把XML文件放在资源目录下通过命名空间和ID来定位具体的SQL语句。对于简单的单表查询用ORM框架自动生成SQL是没问题的。但对于多表关联查询、聚合统计、批量操作手写SQL更可控。手写SQL的时候要注意参数绑定方式用预编译参数而不是字符串拼接防止SQL注入。EOS7.5的ORM框架通常支持#{}和${}两种占位符前者是预编译参数后者是直接替换除非确实需要动态拼接表名或字段名否则一律用#{}。4.5 表现层的参数接收与结果返回表现层接收参数时要区分路径参数、查询参数和请求体参数。路径参数用于标识资源比如订单ID查询参数用于过滤和分页请求体参数用于传递复杂的业务数据。在EOS7.5中可以通过注解来绑定不同类型的参数。结果返回统一用平台提供的响应对象包含状态码、消息和数据体。状态码要区分成功、业务失败和系统异常。业务失败是预期内的比如“余额不足”返回明确的错误码和提示信息系统异常是预期外的比如数据库连接失败返回通用的错误提示同时记录详细的日志供排查。表现层还要处理参数校验失败的情况。我习惯在表现层做基础格式校验校验失败直接返回错误响应不进入业务逻辑层。这样业务逻辑层可以假设传入的参数格式是正确的减少不必要的判断。5. 接口联调与测试中的实战经验5.1 用接口文档工具管理接口定义手写接口最大的痛点之一是接口文档和代码不同步。代码改了文档没改调用方按旧文档调用就会出错。解决办法是用接口文档生成工具从代码注解中自动生成文档。在EOS7.5中可以集成平台自带的文档生成功能也可以引入第三方工具。我习惯在接口定义时就写好注解包括接口用途、参数说明、返回值说明、错误码列表。这样生成的文档直接可用不需要额外维护。注解要写得具体不要写“用户ID”这种显而易见的说明而要写“用户ID必填长度不超过32位”。5.2 单元测试要覆盖业务规则的分支业务逻辑层的单元测试是重中之重。测试用例要覆盖所有业务规则的分支包括正常流程、边界条件和异常流程。比如订单折扣计算要测试不同用户等级、不同商品类型、不同促销活动的组合确保每种组合的计算结果都正确。写单元测试时数据访问层用Mock对象替代这样测试不依赖数据库环境运行速度快而且可以模拟各种数据库异常情况。EOS7.5中可以用平台提供的测试基类也可以引入Mock框架。我通常会把业务逻辑层的测试覆盖率作为代码合并的硬性指标覆盖率不达标不允许合并。5.3 集成测试验证三层之间的协作单元测试验证的是单个类的逻辑集成测试验证的是三层之间的协作。集成测试需要启动完整的应用上下文连接真实的数据库调用表现层接口验证返回结果是否符合预期。集成测试的用例不需要像单元测试那么密集但要覆盖主要的业务流程。比如创建订单、查询订单、取消订单这条主流程要有一个完整的集成测试用例。集成测试中要注意数据清理每个用例执行前把测试数据准备好执行后清理掉避免用例之间相互影响。5.4 性能测试关注事务持有时间和SQL执行效率手写接口的性能瓶颈通常出现在两个地方事务持有时间过长和SQL执行效率低。事务持有时间过长会导致数据库连接被长时间占用并发量一上来就会出现连接池耗尽。SQL执行效率低会导致单个请求响应时间过长影响用户体验。性能测试时我重点关注两个指标事务平均持有时间和慢SQL数量。事务持有时间超过500毫秒就要分析原因看是不是在事务内做了远程调用或者大量计算。慢SQL超过100毫秒就要优化看是不是缺少索引或者查询条件不合理。EOS7.5平台通常提供性能监控工具可以查看这些指标。6. 三层架构手写接口的维护与演进策略6.1 接口变更时的兼容性处理业务需求变化时接口不可避免需要调整。调整接口时第一原则是不破坏现有调用方。如果只是增加返回字段那是兼容的调用方不受影响。如果要修改字段类型或者删除字段那就是不兼容的需要走版本管理流程。我的做法是在接口定义中预留扩展字段比如返回结果中带一个extInfo的Map用于存放后续可能增加的字段。这样小范围的字段增加不需要改接口定义直接往extInfo里放就行。当然这不是长久之计重要的字段还是要正式定义extInfo只用于临时过渡。6.2 业务逻辑层的方法拆分与复用随着业务发展业务逻辑层的方法会越来越复杂。这时候需要及时拆分把可复用的逻辑抽成独立方法。比如订单创建和订单修改都需要计算价格那就把价格计算抽成一个独立方法两个业务方法都调用它。拆分方法时要注意粒度。粒度太粗复用性差粒度太细方法调用链太长调试困难。我的经验是一个方法只做一件事方法名能准确描述这件事。如果方法名里出现了“和”“以及”这样的连接词说明这个方法做了不止一件事应该拆分。6.3 数据访问层的SQL优化与索引调整数据访问层的SQL是随着业务数据量增长最容易出问题的地方。初期数据量小全表扫描也很快数据量上来了没有索引的查询就会变成灾难。所以数据访问层的SQL要定期审查看是否有缺失的索引。审查SQL时我重点关注查询条件中的字段是否有索引、排序字段是否有索引、关联字段是否有索引。EOS7.5平台通常提供SQL执行计划分析工具可以看到SQL实际走了哪些索引。如果发现全表扫描就要考虑加索引或者调整查询条件。6.4 表现层的参数校验规则统一管理表现层的参数校验规则如果散落在各个方法里后续修改校验规则就要翻遍所有代码。更好的做法是把校验规则集中管理比如定义一个校验规则配置文件表现层方法引用配置中的规则。在EOS7.5中可以用平台提供的校验框架通过注解来声明校验规则。注解的好处是校验规则和参数定义在一起一目了然。但注解的缺点是灵活性有限复杂的校验逻辑还是得写代码。我的做法是简单的格式校验用注解复杂的业务校验放在业务逻辑层。6.5 三层架构在微服务拆分中的演进当系统规模变大可能需要把单体应用拆分成微服务。三层架构在微服务拆分中依然适用只是表现层变成了API网关业务逻辑层变成了独立的微服务数据访问层变成了微服务内部的数据库访问。拆分时要注意原来在一个事务里的操作拆分后可能变成跨服务调用无法用本地事务保证一致性。这时候需要引入分布式事务方案比如最终一致性或者补偿事务。EOS7.5平台通常提供分布式事务支持但分布式事务的复杂度远高于本地事务能避免就避免。我的建议是尽量按业务边界拆分让每个微服务内部的事务是完整的跨服务的事务用最终一致性来解决。7. 一些只有实际做过才知道的细节手写接口这件事看别人写觉得很简单自己动手才知道细节有多磨人。我分享几个在实际项目中总结出来的经验都是文档里不会写的。第一个是关于事务注解的传播行为。默认的传播行为是REQUIRED意思是如果当前没有事务就新建一个如果有就加入。这个默认值在大多数情况下是对的但有一种情况要注意如果业务逻辑层的方法被同一个类的另一个方法调用事务注解会失效因为Spring的AOP代理是基于接口的类内部调用不走代理。解决办法是把事务方法抽到独立的类中或者通过接口注入自身来调用。第二个是关于异常处理。业务逻辑层抛出的异常表现层要统一捕获并转换成友好的错误提示。但要注意不要把所有异常都转换成同一种错误码否则排查问题时会很困难。我习惯把异常分为三类参数错误、业务规则错误、系统错误。参数错误返回400业务规则错误返回422系统错误返回500。每类错误都有对应的错误码段方便快速定位。第三个是关于日志。手写接口的日志要记录关键信息包括请求参数、响应结果、执行耗时、异常堆栈。但要注意日志中不要记录敏感信息比如密码、身份证号、银行卡号。EOS7.5平台通常提供日志脱敏功能可以在配置中指定需要脱敏的字段。第四个是关于接口的幂等性。有些接口需要支持重复调用而不产生副作用比如支付接口。实现幂等性的方式有很多可以用唯一业务标识加数据库唯一索引也可以用分布式锁。我倾向于用数据库唯一索引简单可靠。在业务逻辑层的方法入口处先检查业务标识是否已存在存在就直接返回上次的结果不存在才继续执行。第五个是关于分页查询。分页查询看起来简单但细节很多。比如总数查询和列表查询要分开因为总数查询可以走缓存列表查询不行。再比如排序字段要加索引否则分页越往后越慢。还有分页参数要做上限控制防止调用方传入一个巨大的分页大小把数据库拖垮。这些细节每一个都是踩过坑之后才记住的。三层架构的思想本身不复杂难的是在具体项目中坚持执行不被各种“捷径”诱惑。EOS7.5这样的低代码平台提供了很多便利但便利不等于正确该守的规矩还是要守。