最近在技术社区看到一个很有意思的讨论“有没有哪家公司又改回手写代码了” 这背后其实反映了很多开发者在面对日益复杂的低代码、AI生成代码工具时的反思。当项目迭代速度、代码可维护性和团队技术深度产生矛盾时纯粹依赖可视化拖拽或AI生成的“黑盒”代码是否真的是最优解本文将从工程实践的角度深入探讨“手写代码”在当代开发中的核心价值、适用场景并通过一个完整的微服务API开发案例展示如何平衡效率与质量。无论你是面临技术选型的团队负责人还是希望夯实基础的开发者都能从中获得一套可落地的实操方案。1. 背景与核心概念什么是“手写代码”在讨论之前我们需要明确“手写代码”在当前语境下的定义。它并非指拒绝使用任何IDE或代码补全而是强调开发者对代码的完整控制权、清晰的逻辑意图表达以及对底层实现原理的理解。与之相对的是过度依赖以下两种方式低代码/无代码平台通过图形化界面配置生成应用业务逻辑被封装在平台内部开发者难以进行深度定制、性能优化或复杂的底层交互。AI代码生成工具如GitHub Copilot、通义灵码等它们能快速生成代码片段但生成的代码可能缺乏上下文理解、存在隐藏的bug或不符合项目特定的架构规范。“改回手写代码”的现象通常发生在企业遇到以下痛点之后维护成本飙升低代码平台生成的应用在业务复杂后变得难以调试和扩展。性能瓶颈生成的代码效率低下无法满足高并发或实时性要求。供应商锁定平台绑定严重迁移成本极高。团队技术能力退化长期使用“黑盒”工具开发者丧失了解决复杂技术问题的能力。因此这里的“手写代码”更接近“精心设计和编写的源代码”它追求的是可读性、可维护性、可测试性和对系统行为的精确掌控。2. 环境准备与版本说明为了具体展示“手写代码”的实践我们将以一个典型的后端场景——开发一个用户管理模块的RESTful API为例。这个例子涵盖了从项目初始化、数据库交互到API暴露的完整流程强调每一步的手动设计与实现。示例环境与工具语言与框架Java 17 Spring Boot 3.1.x。Spring Boot提高了开发效率但核心业务逻辑仍需我们手动编写。构建工具Maven 3.8 或 Gradle 8.x。本文使用Maven。数据库MySQL 8.0。我们将手动编写SQL建表语句和数据操作逻辑。IDEIntelliJ IDEA或VS Code。它们提供智能补全但不会替我们决定代码结构。API测试工具Postman或cURL。项目结构预览一个清晰的项目结构是良好代码的开始我们将手动创建以下目录src/main/java/com/example/userdemo/ ├── UserDemoApplication.java // 应用主入口 ├── config/ │ └── WebConfig.java // 全局配置如跨域 ├── controller/ │ └── UserController.java // API接口层 ├── service/ │ ├── UserService.java // 业务逻辑接口 │ └── impl/ │ └── UserServiceImpl.java // 业务逻辑实现 ├── repository/ │ ├── entity/ │ │ └── UserEntity.java // 数据库实体类 │ ├── mapper/ │ │ └── UserMapper.java // 数据访问接口MyBatis │ └── UserRepository.java // 数据访问层抽象可选JPA风格 └── dto/ ├── UserDTO.java // 数据传输对象API出参 └── CreateUserRequest.java // 请求对象API入参这个结构严格遵循了分层架构Controller-Service-Repository职责分离便于维护和测试。3. 核心思想与设计原则在动手写代码前确立正确的设计原则至关重要。这决定了代码的长期生命力。3.1 清晰优于巧妙“手写代码”不意味着要写晦涩难懂的“炫技”代码。恰恰相反它的最高标准是清晰。变量名、方法名要能准确表达其意图。避免使用魔法数字用常量或枚举替代。例如// 不推荐魔法数字意图不明 if (user.getStatus() 1) { ... } // 推荐使用枚举清晰表达业务状态 public enum UserStatus { ACTIVE, INACTIVE, PENDING } if (user.getStatus() UserStatus.ACTIVE) { ... }3.2 单一职责原则每个类、每个方法只做一件事并且做好。这能极大降低代码的复杂度提高可测试性。例如一个UserService中的方法应该只关注用户相关的业务逻辑而不应该包含发送邮件的细节。3.3 依赖注入与松耦合通过Spring的依赖注入DI容器来管理对象间的依赖关系而不是在类内部直接new对象。这使得代码更容易进行单元测试和模块替换。Service public class UserServiceImpl implements UserService { // 通过构造函数注入而非 Autowired 字段注入推荐方式 private final UserRepository userRepository; public UserServiceImpl(UserRepository userRepository) { this.userRepository userRepository; // 依赖被注入 } Override public UserDTO getUserById(Long id) { // 业务逻辑 return userRepository.findById(id).map(this::convertToDTO).orElse(null); } }3.4 防御式编程与异常处理对输入参数进行校验对可能失败的操作进行预判和妥善处理。使用Java Bean Validation或自定义校验逻辑。PostMapping(/users) public ResponseEntityUserDTO createUser(Valid RequestBody CreateUserRequest request) { // Valid 会自动校验CreateUserRequest中定义的约束如NotBlank UserEntity savedUser userService.createUser(request); return ResponseEntity.status(HttpStatus.CREATED).body(convertToDTO(savedUser)); }同时定义清晰的业务异常并在全局进行统一处理避免将底层异常直接暴露给API调用者。4. 完整实战案例手写用户管理API接下来我们从头开始构建这个API。请注意每一步都包含了“为什么这么做”的思考。4.1 初始化Spring Boot项目与依赖使用 start.spring.io 或IDE创建项目手动选择并添加以下核心依赖到pom.xmldependencies !-- Web支持 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 数据访问 (使用MyBatis-Plus示例) -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency !-- MySQL驱动 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency !-- 参数校验 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId /dependency !-- Lombok (简化Getter/Setter等可选但推荐) -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies为什么选择MyBatis-Plus它保留了手写SQL的灵活性当需要复杂查询时同时提供了强大的单表CRUD封装避免了大量简单重复的Mapper编写是“手写”与“效率”的一个良好平衡点。4.2 数据库设计与实体类映射首先在MySQL中手动执行DDL语句创建表CREATE TABLE t_user ( id bigint NOT NULL AUTO_INCREMENT COMMENT 主键ID, username varchar(64) NOT NULL COMMENT 用户名, email varchar(128) NOT NULL COMMENT 邮箱, status varchar(20) NOT NULL DEFAULT ACTIVE COMMENT 用户状态: ACTIVE, INACTIVE, created_at datetime DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, updated_at datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新时间, PRIMARY KEY (id), UNIQUE KEY uk_username (username), UNIQUE KEY uk_email (email) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT用户表;然后在Java中创建对应的实体类UserEntitypackage com.example.userdemo.repository.entity; import com.baomidou.mybatisplus.annotation.*; import lombok.Data; import java.time.LocalDateTime; Data TableName(t_user) // 指定表名 public class UserEntity { TableId(type IdType.AUTO) // 主键自增 private Long id; private String username; private String email; private String status; // 实际项目中更推荐用枚举类型这里为简化用String TableField(fill FieldFill.INSERT) // 插入时自动填充 private LocalDateTime createdAt; TableField(fill FieldFill.INSERT_UPDATE) // 插入和更新时自动填充 private LocalDateTime updatedAt; }这里我们使用了Lombok的Data来简化Getter/Setter但字段映射关系、主键策略、自动填充规则都是我们手动明确指定的这保证了数据库层行为的可控性。4.3 编写数据访问层Repository/Mapper创建Mapper接口UserMapperpackage com.example.userdemo.repository.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.example.userdemo.repository.entity.UserEntity; import org.apache.ibatis.annotations.Mapper; Mapper public interface UserMapper extends BaseMapperUserEntity { // 继承BaseMapper已具备基本CRUD方法。 // 复杂查询可以在这里定义方法并在对应的XML文件中手写SQL。 }同时可以创建一个Repository接口作为业务层和数据层之间的抽象这是一个良好的设计习惯package com.example.userdemo.repository; import com.example.userdemo.repository.entity.UserEntity; import java.util.Optional; public interface UserRepository { UserEntity save(UserEntity user); OptionalUserEntity findById(Long id); OptionalUserEntity findByUsername(String username); void deleteById(Long id); // ... 其他查询方法 }然后提供基于MyBatis-Plus的实现类UserRepositoryImpl注入UserMapper来实现这些方法。这层抽象使得未来更换数据访问技术如切到JPA或MongoDB时业务层代码无需改动。4.4 定义DTO与请求对象为了避免实体类直接暴露给API层防止数据泄露和耦合我们创建数据传输对象DTO和请求对象。package com.example.userdemo.dto; import lombok.Data; import javax.validation.constraints.Email; import javax.validation.constraints.NotBlank; Data public class CreateUserRequest { NotBlank(message 用户名不能为空) private String username; NotBlank(message 邮箱不能为空) Email(message 邮箱格式不正确) private String email; } Data public class UserDTO { private Long id; private String username; private String email; private String status; private LocalDateTime createdAt; // 注意通常不返回密码等敏感字段 }4.5 实现业务逻辑层Service这是“手写代码”体现业务复杂性的核心。在UserServiceImpl中我们实现具体的业务规则。package com.example.userdemo.service.impl; Service Slf4j // Lombok注解自动提供log实例 public class UserServiceImpl implements UserService { private final UserRepository userRepository; public UserServiceImpl(UserRepository userRepository) { this.userRepository userRepository; } Override public UserDTO createUser(CreateUserRequest request) { // 1. 业务校验即使有Valid复杂的业务校验也要在这里做 userRepository.findByUsername(request.getUsername()).ifPresent(u - { throw new BusinessException(用户名已存在); }); userRepository.findByEmail(request.getEmail()).ifPresent(u - { throw new BusinessException(邮箱已注册); }); // 2. 对象转换Request - Entity UserEntity newUser new UserEntity(); newUser.setUsername(request.getUsername()); newUser.setEmail(request.getEmail()); newUser.setStatus(ACTIVE); // 3. 持久化操作 UserEntity savedUser userRepository.save(newUser); log.info(用户创建成功ID: {}, savedUser.getId()); // 4. 返回结果Entity - DTO return convertToDTO(savedUser); } Override public UserDTO getUserById(Long id) { return userRepository.findById(id) .map(this::convertToDTO) .orElseThrow(() - new ResourceNotFoundException(用户不存在)); } // 私有转换方法 private UserDTO convertToDTO(UserEntity entity) { if (entity null) return null; UserDTO dto new UserDTO(); dto.setId(entity.getId()); dto.setUsername(entity.getUsername()); dto.setEmail(entity.getEmail()); dto.setStatus(entity.getStatus()); dto.setCreatedAt(entity.getCreatedAt()); return dto; } }注意这里我们抛出了自定义的业务异常BusinessException,ResourceNotFoundException这些异常会在Controller层被统一捕获并转换为友好的HTTP错误响应。4.6 编写API接口层ControllerController层应保持“薄”主要负责HTTP协议相关的处理如路由、参数绑定、状态码返回。package com.example.userdemo.controller; RestController RequestMapping(/api/v1/users) public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService userService; } PostMapping ResponseStatus(HttpStatus.CREATED) // 创建成功返回201 public UserDTO createUser(Valid RequestBody CreateUserRequest request) { return userService.createUser(request); } GetMapping(/{id}) public UserDTO getUser(PathVariable Long id) { return userService.getUserById(id); } }4.7 配置与运行在application.yml中配置数据库连接和应用端口spring: datasource: url: jdbc:mysql://localhost:3306/user_demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver server: port: 8080 mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 控制台打印SQL调试用启动主类UserDemoApplication应用将在8080端口启动。4.8 使用Postman测试API创建用户POST http://localhost:8080/api/v1/usersBody (JSON):{ username: testuser, email: testexample.com }预期返回201 Created并带有生成的用户信息。查询用户GET http://localhost:8080/api/v1/users/1预期返回200 OK以及ID为1的用户信息。5. 常见问题与排查思路在“手写代码”的过程中你可能会遇到以下典型问题问题现象可能原因排查步骤与解决方案应用启动失败报BeanCreationException1. 依赖缺失或版本冲突。2. Bean注入失败如找不到实现类。3. 配置错误如数据库连接失败。1. 检查pom.xml依赖使用mvn dependency:tree查看冲突。2. 检查Service,Repository,Component注解是否添加包扫描路径是否正确。3. 检查application.yml配置特别是数据库URL、用户名密码。调用API返回400 Bad Request1. 请求参数格式错误JSON语法错误。2. 参数校验失败如NotBlank校验未通过。1. 使用Postman等工具检查JSON格式。2. 查看应用日志Spring Boot会详细输出校验失败信息。调用API返回404 Not Found1. 请求URL路径错误。2. Controller方法未被映射如RequestMapping路径错误。1. 核对API文档或代码中的RequestMapping和GetMapping等注解路径。2. 启动应用后访问/actuator/mappings端点需引入actuator依赖查看所有映射。数据库操作失败报SQLSyntaxErrorException1. 实体类字段名与数据库列名映射错误。2. SQL语句错误在手写复杂SQL时常见。1. 检查TableField注解的value值是否与数据库列名一致。2. 打开MyBatis-Plus的SQL日志查看实际执行的SQL语句进行调试。事务不生效1. 方法未被Spring事务管理。2. 异常类型未被回滚默认只回滚RuntimeException。1. 在Service方法上添加Transactional注解。2. 检查是否抛出了被try-catch吞掉的异常或指定Transactional(rollbackFor Exception.class)。6. 最佳实践与工程建议回归“手写代码”的本质是为了获得更高的工程质量以下实践能帮助你更好地达成这一目标6.1 代码质量与规范静态代码分析集成SonarQube、Checkstyle、PMD等工具在CI/CD流水线中强制进行代码质量门禁。统一的代码风格使用Google Java Format或Spotless插件确保团队代码风格一致。清晰的提交信息使用Conventional Commits规范使提交历史可读性强便于生成变更日志。6.2 测试策略“手写代码”必须伴随充分的测试否则可控性将无从谈起。单元测试对Service层的核心业务逻辑进行测试使用Mockito模拟依赖。确保覆盖率特别是分支覆盖。集成测试测试Controller层API可以使用SpringBootTest和TestRestTemplate对数据库使用Testcontainers或H2内存数据库。契约测试如果涉及多服务交互使用Pact等工具进行契约测试确保API接口的兼容性。6.3 文档与注释代码即文档通过清晰的命名、合理的结构让代码自身表达意图。注释应解释“为什么这么做”业务原因、设计决策而不是“做什么”代码已经表达了。API文档使用Spring Doc OpenAPISwagger自动生成可交互的API文档并保持更新。6.4 平衡“手写”与“工具”“手写代码”不是排斥一切工具。聪明的做法是使用IDE智能补全提高编码速度避免拼写错误。使用代码片段Live Templates将常用的、规范的代码结构如日志声明、DTO转换保存为模板。使用AI辅助让Copilot等工具生成一些模板代码如Getter/Setter、简单的Mapper方法但必须仔细审查和修改理解每一行代码的含义并使其符合项目规范。使用代码生成器对于极其重复的CRUD代码可以使用MyBatis-Plus Generator等工具生成基础代码然后在其基础上进行深度定制和业务逻辑填充。6.5 持续重构随着业务发展最初“手写”的代码也可能变得混乱。建立持续重构的文化定期审查代码识别坏味道如过长方法、过大类、重复代码并运用设计模式进行优化。回归“手写代码”是一种技术决策更是一种工程哲学的选择。它要求开发者重新成为代码的真正主人深入理解每一行代码背后的逻辑与代价。通过本文的案例我们可以看到从清晰的分层设计、严谨的实体映射到充满业务细节的Service实现每一步都体现了开发者的掌控力和设计意图。这种掌控力带来的直接收益是系统更易维护、性能更可优化、团队技术能力可持续成长。当然这并不意味着我们要回到“刀耕火种”的时代而是倡导在充分利用现代开发工具提升效率的同时牢牢守住对核心业务逻辑和系统架构的深刻理解与亲手塑造的能力。对于追求长期稳定、高性能和可演进性的项目而言这份“手写”的功底无疑是团队最宝贵的财富。