通义灵码 Project Rules

在开始体验通义灵码 Project Rules 之前，我们先来简单了解一下什么是 通义灵码 Project Rules ？大家都知道，在适用AI 代码助手的时候，有时候生成的代码不是自己想要的，或者说生成的代码采纳后还需要人工修改一部分。这其实就是当模型对于你的描述不能正确理解，或者说理解了你的描述，但是没有适当的方案时，大模型会根据自己的规则来生成相似的自己认为对的代码。这就是我们常说的模型幻觉。那么当模型生成代码不精准的时候，是否用什么手段可以硬控 AI 根据你的代码风格和偏好生成代码和回复，现在有了，你可以感受一下通义灵码 Project Rules的效果。

举个例子

这里我们来举个小例子，比如我想要使用阿里云百炼服务平台的模型来在自己的项目中引入一个 deepseek 的调用，那么我就可以拿到阿里云百炼服务平台的 curl 的调用方法

复制curl 的调用内容放在通义灵码的对话框中，输入我想要的内容

curl -X POST "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "deepseek-r1",
    "input":{
        "messages":[      
            {
                "role": "user",
                "content": "你是谁？"
            }
        ]
    },
    "parameters": {
        "result_format": "message"
    }
}' 生成java代码

以下是通义灵码为我们生成的使用Java 调用deepseek 的API 接口的调用工具类

这里通过截图我们可以看到，生成的代码基本上没有注释，生成的效果功能上稍作改动就可以用，采纳率95%以上。下面我们再来为通义灵码定义AI 编码规则，定义完AI 编码规则之后再来看一下基于上面的 curl 调用方法生成的Java 代码的效果。

环境准备

在配置通义灵码 Project Rules AI编码规则之前，首先需要我们确认一下我们的通义灵码插件版本是否在 v2.1.5 及以上

规则配置

这里我们在IDEA 开发工具的 setting 弹框中找到【Lingma】,勾选启用并点击【编辑】

在编辑页面输入具体的编码规则 Project Rules ，这里的规则我们直接使用官方提供的java 编码规则，具体规则内容的markdown 语法格式如下

你是一个资深的java专家，请在开发中遵循如下规则：

严格遵循 SOLID、DRY、KISS、YAGNI 原则
遵循 OWASP 安全最佳实践（如输入验证、SQL注入防护）
采用 分层架构设计，确保职责分离
代码变更需通过 单元测试覆盖（测试覆盖率 ≥ 80%）
二、技术栈规范
技术栈要求
框架：Spring Boot 3.x + Java 17
依赖：
核心：Spring Web, Spring Data JPA, Lombok
数据库：PostgreSQL Driver 或其他关系型数据库驱动
其他：Swagger (SpringDoc), Spring Security (如需权限控制)
三、应用逻辑设计规范
1. 分层架构原则
层级	职责	约束条件
Controller	处理 HTTP 请求与响应，定义 API 接口	- 禁止直接操作数据库
- 必须通过 Service 层调用
Service	业务逻辑实现，事务管理，数据校验	- 必须通过 Repository 访问数据库
- 返回 DTO 而非实体类（除非必要）
Repository	数据持久化操作，定义数据库查询逻辑	- 必须继承 JpaRepository
- 使用 @EntityGraph 避免 N+1 查询问题
Entity	数据库表结构映射对象	- 仅用于数据库交互
- 禁止直接返回给前端（需通过 DTO 转换）
四、核心代码规范
1. 实体类（Entity）规范
@Entity
@Data // Lombok 注解
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 50)
    private String username;

    @Email
    private String email;

    // 关联关系使用懒加载
    @ManyToOne(fetch = FetchType.LAZY)
    private Department department;
}
2. 数据访问层（Repository）规范
public interface UserRepository extends JpaRepository<User, Long> {
    // 命名查询
    Optional<User> findByUsername(String username);

    // 自定义 JPQL 查询
    @Query("SELECT u FROM User u JOIN FETCH u.department WHERE u.id = :id")
    @EntityGraph(attributePaths = {"department"})
    Optional<User> findUserWithDepartment(@Param("id") Long id);
}
3. 服务层（Service）规范
@Service
public class UserServiceImpl implements UserService {
    @Autowired
    private UserRepository userRepository;

    @Transactional
    public ApiResponse<UserDTO> createUser(UserDTO dto) {
        // 业务逻辑实现
        User user = User.builder().username(dto.getUsername()).build();
        User savedUser = userRepository.save(user);
        return ApiResponse.success(UserDTO.fromEntity(savedUser));
    }
}
4. 控制器（RestController）规范
@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private UserService userService;

    @PostMapping
    public ResponseEntity<ApiResponse<UserDTO>> createUser(@RequestBody @Valid UserDTO dto) {
        try {
            ApiResponse<UserDTO> response = userService.createUser(dto);
            return ResponseEntity.ok(response);
        } catch (Exception e) {
            return GlobalExceptionHandler.errorResponseEntity(e.getMessage(), HttpStatus.BAD_REQUEST);
        }
    }
}
五、数据传输对象（DTO）规范
// 使用 record 或 @Data 注解
public record UserDTO(
    @NotBlank String username,
    @Email String email
) {
    public static UserDTO fromEntity(User entity) {
        return new UserDTO(entity.getUsername(), entity.getEmail());
    }
}
六、全局异常处理规范
1. 统一响应类（ApiResponse）
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ApiResponse<T> {
    private String result; // SUCCESS/ERROR
    private String message;
    private T data;

    // 工厂方法
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>("SUCCESS", "操作成功", data);
    }

    public static <T> ApiResponse<T> error(String message) {
        return new ApiResponse<>("ERROR", message, null);
    }
}
2. 全局异常处理器（GlobalExceptionHandler）
@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(EntityNotFoundException.class)
    public ResponseEntity<ApiResponse<?>> handleEntityNotFound(EntityNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
            .body(ApiResponse.error(ex.getMessage()));
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiResponse<?>> handleValidationErrors(MethodArgumentNotValidException ex) {
        String errorMessage = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(error -> error.getField() + ": " + error.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return ResponseEntity.badRequest().body(ApiResponse.error(errorMessage));
    }
}
七、安全与性能规范
输入校验：
使用 @Valid 注解 + JSR-303 校验注解（如 @NotBlank, @Size）
禁止直接拼接 SQL 防止注入攻击
事务管理：
@Transactional 注解仅标注在 Service 方法上
避免在循环中频繁提交事务
性能优化：
使用 @EntityGraph 预加载关联关系
避免在循环中执行数据库查询（批量操作优先）
八、代码风格规范
命名规范：
类名：UpperCamelCase（如 UserServiceImpl）
方法/变量名：lowerCamelCase（如 saveUser）
常量：UPPER_SNAKE_CASE（如 MAX_LOGIN_ATTEMPTS）
注释规范：
方法必须添加注释且方法级注释使用 Javadoc 格式
计划待完成的任务需要添加 // TODO 标记
存在潜在缺陷的逻辑需要添加 // FIXME 标记
代码格式化：
使用 IntelliJ IDEA 默认的 Spring Boot 风格
禁止手动修改代码缩进（依赖 IDE 自动格式化）
九、部署规范
部署规范：
生产环境需禁用 @EnableAutoConfiguration 的默认配置
敏感信息通过 application.properties 外部化配置
使用 Spring Profiles 管理环境差异（如 dev, prod）
十、扩展性设计规范
接口优先：
服务层接口（UserService）与实现（UserServiceImpl）分离
扩展点预留：
关键业务逻辑需提供 Strategy 或 Template 模式支持扩展
日志规范：
使用 SLF4J 记录日志（禁止直接使用 System.out.println）
核心操作需记录 INFO 级别日志，异常记录 ERROR 级别

再增加了 rules 规则之后，我们再来执行一次上面基于 curl 请求生成java 调用代码的需求，执行之后，我们可以看到对第一次生成的 DeepSeekClient.java 类进行了按照 rules 规则的变更


可以看到已经按照我们添加的异常处理规则以及编码规范进行了优化。
编辑后的灵码规则文件的的位置在项目的具体目录位置如图，如果没有看到的话刷新一下磁盘就看到了