企业官网建设流程全解析

1. 为什么要在EOS7.5里手写接口

EOS7.5这套低代码/快速开发平台，很多团队用它的可视化编排、页面建模和流程引擎来搭业务系统。但真正落到项目里，纯靠平台内置的构件和自动生成，往往会在复杂业务逻辑、跨系统交互、性能敏感场景上卡住。这时候，手写接口就成了绕不开的一环。

所谓手写接口，就是在EOS7.5的工程结构里，不依赖平台自动生成的那套代码，而是自己按三层架构的方式，把表现层、业务逻辑层、数据访问层拆开，手动编写Java接口和实现类，再通过平台的构件机制暴露出去。这样做的好处很直接：逻辑可控、调试方便、复用性高，而且代码结构符合标准的编程思想，后续维护的人一看就懂。

我见过不少项目，前期图快，全部用平台拖拽生成，结果业务一复杂，代码变成一团乱麻，改一个字段要翻五六个自动生成的类，最后不得不推倒重来。手写接口虽然前期多花点时间，但后期省下的维护成本是成倍的。这篇文章适合正在用EOS7.5做项目、遇到平台生成代码不够用、想自己掌控核心逻辑的开发者，也适合刚接触这个平台、想理解它工程结构的人。

2. 三层架构在EOS7.5中的落地思路

2.1 三层架构的核心分工

三层架构不是什么新概念，但放在EOS7.5这个特定平台里，需要结合它的工程结构和构件机制来落地。简单说，三层分别是：

• 表现层：负责接收外部请求、参数校验、结果封装。在EOS7.5里，这一层通常对应平台的构件入口，比如一个逻辑流构件或者自定义的REST服务入口。
• 业务逻辑层：核心业务规则、事务控制、流程编排都在这里。这一层是手写代码的主战场，也是最能体现编程思想的地方。
• 数据访问层：负责和数据库打交道，SQL执行、结果集映射、连接管理。EOS7.5本身有数据访问构件，但手写接口时，我倾向于自己封装一层DAO，方便控制SQL和缓存。

这样拆的好处是，每一层只关心自己的事。表现层不关心数据从哪来，业务层不关心请求怎么进来，数据层不关心业务规则。改一处不影响其他层，测试也好做。

2.2 为什么不用平台全自动生成

EOS7.5的自动生成能力确实强，建个数据模型就能生成增删改查的构件和页面。但问题在于，自动生成的代码是通用模板，它不知道你的业务规则。比如一个订单金额计算，涉及折扣、税费、优惠券叠加，自动生成的代码根本处理不了，你只能在它生成的代码上打补丁，补丁越打越多，最后没人敢动。

手写接口的思路是：平台负责它擅长的部分，比如页面渲染、流程流转、权限控制；核心业务逻辑我自己写，通过接口和平台对接。这样既享受了平台的便利，又保住了代码的可控性。

2.3 接口设计的基本原则

手写接口不是随便写个类就行，得遵循几个原则：

• 接口与实现分离：先定义接口，再写实现类。这样业务层调用的是接口，具体实现可以换，方便做多态和单元测试。
• 单一职责：一个接口只做一件事。比如订单查询接口和订单创建接口分开，不要混在一起。
• 参数和返回值用DTO：不要直接传Map或者实体类，用专门的数据传输对象，字段清晰，序列化可控。
• 异常统一处理：业务异常和系统异常分开，表现层统一捕获，返回友好的错误信息。

这些原则听起来老生常谈，但在EOS7.5项目里，很多人因为赶进度就忽略了，最后代码质量惨不忍睹。

3. 手写接口的核心细节与实操要点

3.1 工程结构怎么建

在EOS7.5的工程里，我一般会建这么几个包：

• com.xxx.project.api：放接口定义，纯接口，不带任何实现。
• com.xxx.project.service：放业务逻辑实现类。
• com.xxx.project.dao：放数据访问类。
• com.xxx.project.dto：放数据传输对象。
• com.xxx.project.common：放工具类、常量、异常定义。

这个结构不是死的，但核心思想是分层清晰。EOS7.5的工程本身有它的目录规范，手写的代码放在src目录下，编译后和平台生成的代码一起打包。注意不要和平台自动生成的包名冲突，否则会出现类加载问题。

3.2 接口定义怎么写

接口定义要简洁明了，方法名用动词开头，参数和返回值用DTO。举个例子：

public interface OrderService { OrderResultDTO createOrder(OrderCreateDTO dto) throws BusinessException; OrderResultDTO queryOrder(OrderQueryDTO dto) throws BusinessException; boolean cancelOrder(String orderId) throws BusinessException; }

这里OrderCreateDTO里放创建订单需要的所有参数，OrderResultDTO里放返回结果。BusinessException是自定义的业务异常，继承自RuntimeException，方便事务回滚。

注意：接口里不要抛Exception这种宽泛的异常，要抛具体的业务异常，这样调用方知道怎么处理。

3.3 业务逻辑层的实现要点

业务逻辑层的实现类，我一般会加@Service注解（如果用了Spring），或者用EOS7.5自己的构件注解。核心逻辑包括：

• 参数校验：不要信任外部传入的参数，该判空判空，该校验格式校验格式。
• 事务控制：涉及多表写入的操作，一定要加事务。EOS7.5支持声明式事务，在方法上加注解即可。
• 业务规则：这是最核心的部分，比如订单金额计算、库存扣减、状态流转，都要在这里实现。
• 日志记录：关键步骤打日志，方便排查问题。但不要打太多，否则日志文件爆炸。

public class OrderServiceImpl implements OrderService { private OrderDao orderDao; private InventoryDao inventoryDao; @Override @Transactional public OrderResultDTO createOrder(OrderCreateDTO dto) throws BusinessException { // 参数校验 if (dto.getUserId() == null) { throw new BusinessException("用户ID不能为空"); } // 库存检查 int stock = inventoryDao.getStock(dto.getProductId()); if (stock < dto.getQuantity()) { throw new BusinessException("库存不足"); } // 扣减库存 inventoryDao.reduceStock(dto.getProductId(), dto.getQuantity()); // 创建订单 Order order = new Order(); // ... 组装订单对象 orderDao.insert(order); // 返回结果 OrderResultDTO result = new OrderResultDTO(); result.setOrderId(order.getId()); return result; } }

这段代码看起来简单，但每一步都有讲究。参数校验放在最前面，快速失败；库存检查用数据库行锁或者乐观锁，防止超卖；事务注解保证扣库存和创建订单要么都成功，要么都回滚。

3.4 数据访问层的封装

EOS7.5本身有数据访问构件，但手写接口时，我更喜欢自己封装一个轻量的DAO。原因有两个：一是平台构件在复杂SQL场景下不够灵活，二是自己写的DAO更容易做缓存和批处理。

public class OrderDao { public void insert(Order order) { String sql = "INSERT INTO t_order (id, user_id, product_id, quantity, amount, status) VALUES (?, ?, ?, ?, ?, ?)"; // 使用平台的数据库连接或者自己管理的连接池执行SQL } public Order findById(String orderId) { String sql = "SELECT * FROM t_order WHERE id = ?"; // 执行查询并映射结果 return null; } }

这里的关键是SQL要写好，索引要用上。我见过太多项目，SQL写得随意，数据量一上来就慢得不行。手写DAO的好处就是SQL完全可控，该加索引加索引，该优化优化。

实操心得：DAO层不要写业务逻辑，只做数据存取。业务逻辑放在Service层，这样职责清晰，也方便复用。

4. 完整实操流程与关键环节实现

4.1 从零开始建一个手写接口

假设我们要做一个用户注册接口，完整流程如下：

第一步：定义DTO

public class UserRegisterDTO { private String username; private String password; private String email; // getter和setter省略 } public class UserRegisterResultDTO { private String userId; private boolean success; private String message; // getter和setter省略 }

第二步：定义接口

public interface UserService { UserRegisterResultDTO register(UserRegisterDTO dto) throws BusinessException; }

第三步：实现业务逻辑

public class UserServiceImpl implements UserService { private UserDao userDao; @Override @Transactional public UserRegisterResultDTO register(UserRegisterDTO dto) throws BusinessException { // 校验用户名是否已存在 if (userDao.findByUsername(dto.getUsername()) != null) { throw new BusinessException("用户名已存在"); } // 密码加密 String encryptedPassword = encryptPassword(dto.getPassword()); // 创建用户 User user = new User(); user.setUsername(dto.getUsername()); user.setPassword(encryptedPassword); user.setEmail(dto.getEmail()); user.setCreateTime(new Date()); userDao.insert(user); // 返回结果 UserRegisterResultDTO result = new UserRegisterResultDTO(); result.setUserId(user.getId()); result.setSuccess(true); result.setMessage("注册成功"); return result; } private String encryptPassword(String password) { // 使用MD5或者BCrypt加密 return password; } }

第四步：实现DAO

public class UserDao { public User findByUsername(String username) { String sql = "SELECT * FROM t_user WHERE username = ?"; // 执行查询 return null; } public void insert(User user) { String sql = "INSERT INTO t_user (id, username, password, email, create_time) VALUES (?, ?, ?, ?, ?)"; // 执行插入 } }

第五步：在EOS7.5中暴露接口

这一步是关键。EOS7.5有自己的构件机制，手写的接口需要通过平台的构件包装才能被外部调用。一般做法是创建一个逻辑流构件，在构件里调用手写的Service方法，然后把结果返回。

public class UserRegisterComponent { public UserRegisterResultDTO execute(UserRegisterDTO dto) { UserService userService = new UserServiceImpl(); try { return userService.register(dto); } catch (BusinessException e) { UserRegisterResultDTO result = new UserRegisterResultDTO(); result.setSuccess(false); result.setMessage(e.getMessage()); return result; } } }

这样，平台的前端页面或者流程就能调用这个构件，间接调用到手写的业务逻辑。

4.2 参数校验的细节

参数校验看起来简单，但实际项目里最容易出问题。我一般分三层校验：

• 前端校验：页面上的必填、格式校验，这是第一道防线，但不可靠，因为可以绕过。
• 接口层校验：在Service方法入口做校验，用注解或者手动判断。这是最关键的，因为所有调用都会经过这里。
• 数据库约束：字段非空、唯一索引，这是最后一道防线。

public UserRegisterResultDTO register(UserRegisterDTO dto) throws BusinessException { if (dto == null) { throw new BusinessException("请求参数不能为空"); } if (StringUtils.isBlank(dto.getUsername())) { throw new BusinessException("用户名不能为空"); } if (dto.getUsername().length() > 50) { throw new BusinessException("用户名长度不能超过50"); } // ... 其他校验 }

注意：校验信息要友好，不要直接抛“NullPointerException”这种，用户看不懂。

4.3 事务控制的实操

EOS7.5支持声明式事务，在方法上加@Transactional注解即可。但有几个坑要注意：

• 事务方法必须是public：private方法加注解无效。
• 自调用失效：同一个类里A方法调用B方法，B方法的事务注解不生效。解决办法是把B方法放到另一个类里，或者用AOP代理。
• 异常回滚：默认只对RuntimeException回滚，如果抛的是Exception，需要手动设置rollbackFor。

@Transactional(rollbackFor = Exception.class) public void createOrder(OrderCreateDTO dto) throws BusinessException { // ... }

4.4 日志和异常处理

日志是排查问题的命根子。我一般在Service方法入口和出口打日志，记录请求参数和返回结果。但要注意脱敏，密码、身份证号这些不能打。

private static final Logger logger = LoggerFactory.getLogger(UserServiceImpl.class); public UserRegisterResultDTO register(UserRegisterDTO dto) throws BusinessException { logger.info("用户注册开始，用户名：{}", dto.getUsername()); try { // ... 业务逻辑 logger.info("用户注册成功，用户ID：{}", user.getId()); return result; } catch (BusinessException e) { logger.warn("用户注册失败，原因：{}", e.getMessage()); throw e; } catch (Exception e) { logger.error("用户注册异常", e); throw new BusinessException("系统繁忙，请稍后重试"); } }

异常处理的原则是：业务异常直接抛，系统异常包装后抛，不要让底层异常暴露给用户。

5. 常见问题与排查技巧实录

5.1 类加载冲突

EOS7.5平台本身有一堆依赖包，手写代码引入的第三方库如果版本冲突，会出现NoSuchMethodError或者ClassNotFoundException。解决办法是：

• 用mvn dependency:tree查看依赖树，排除冲突的包。
• 尽量用平台已有的库，不要重复引入。
• 如果必须引入，用provided作用域，让平台提供。

5.2 事务不生效

前面提到过，事务不生效最常见的原因是自调用和异常类型不对。排查步骤：

1. 确认方法是不是public。
2. 确认是不是从外部调用，而不是类内部调用。
3. 确认异常是不是RuntimeException，或者有没有设置rollbackFor。
4. 确认Spring事务管理器有没有配置正确。

5.3 SQL性能问题

手写DAO最容易出的问题就是SQL慢。排查方法：

• 开启SQL日志，看实际执行的SQL。
• 用EXPLAIN分析执行计划，看有没有走索引。
• 检查有没有全表扫描、笛卡尔积、隐式类型转换。
• 数据量大的查询，考虑分页和缓存。

实操心得：我一般会在DAO层加一个慢SQL日志，超过500毫秒的SQL自动打警告，方便及时发现性能问题。

5.4 接口调用超时

EOS7.5的构件调用有超时设置，如果手写接口执行时间太长，会被平台中断。解决办法：

• 优化业务逻辑，减少不必要的数据库操作。
• 把耗时操作异步化，比如发消息队列。
• 调整平台的超时配置，但这是治标不治本。

5.5 常见问题速查表

6. 代码编程思想的体现

6.1 面向接口编程

手写接口的核心思想就是面向接口编程。Service层定义接口，实现类可以有多个。比如订单服务，可以有普通订单实现、秒杀订单实现、团购订单实现，调用方只依赖接口，不关心具体实现。这样扩展性强，也方便做单元测试。

6.2 单一职责与开闭原则

每个类只做一件事，这是单一职责。新增功能时，尽量不改原有代码，而是新增类或者方法，这是开闭原则。比如订单金额计算，不同促销策略用不同的计算类，通过策略模式切换，而不是在一个方法里写一堆if-else。

6.3 依赖倒置

高层模块不依赖低层模块，两者都依赖抽象。Service层依赖DAO接口，而不是具体的DAO实现。这样DAO换实现，Service不用改。

public interface OrderDao { void insert(Order order); Order findById(String orderId); } public class OrderDaoImpl implements OrderDao { // 具体实现 } public class OrderServiceImpl implements OrderService { private OrderDao orderDao; // 依赖接口，不是实现 public OrderServiceImpl(OrderDao orderDao) { this.orderDao = orderDao; } }

这种写法在EOS7.5项目里可能显得有点“重”，但正是这种“重”让代码更健壮、更可维护。

6.4 组合优于继承

能组合就不要继承。继承会带来强耦合，父类改一点，子类全受影响。组合更灵活，通过注入不同的实现来改变行为。

7. 我踩过的坑和实操建议

第一个坑是包名冲突。EOS7.5自动生成的代码包名一般是com.primeton.xxx，手写代码如果也用这个前缀，很容易冲突。我后来统一用com.company.project，和平台代码分开，问题就少了。

第二个坑是事务注解加在接口上。Spring的事务注解要加在实现类的方法上，加在接口上不生效。这个坑我踩过两次，后来养成习惯，只在实现类上加。

第三个坑是日志打太多。有一次排查问题，日志级别开到DEBUG，结果一天生成几十G日志，磁盘直接满了。后来改成关键步骤打INFO，详细数据打DEBUG，并且设置日志滚动策略。

第四个坑是SQL没加索引。一个查询接口，数据量才几万条，但响应要好几秒。后来用EXPLAIN一看，全表扫描。加了个索引，直接降到几十毫秒。手写DAO一定要关注索引。

第五个坑是异常吞掉。有些代码catch了异常但不处理，也不打日志，出了问题根本不知道。我的原则是：要么处理，要么抛出，绝不吞掉。

最后分享一个小技巧：手写接口的单元测试一定要写。EOS7.5的构件测试比较麻烦，但Service层和DAO层的单元测试很好写。用JUnit加Mockito，把依赖mock掉，测试业务逻辑。这样改代码的时候，跑一遍测试就知道有没有破坏原有功能。我现在的习惯是，每写一个Service方法，就配一个单元测试，虽然多花十分钟，但省下的调试时间远不止十分钟。