通义灵码 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%）

技术栈规范

技术栈要求：

1）框架：Spring Boot 3.x + Java 17

2）依赖：

• 核心：Spring Web, Spring Data JPA, Lombok
• 数据库：PostgreSQL Driver 或其他关系型数据库驱动
• 其他：Swagger (SpringDoc), Spring Security (如需权限控制)

应用逻辑设计规范

分层架构原则

核心代码规范

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));
    }
}

安全与性能规范

1. 输入校验：

• 使用 @Valid 注解 + JSR-303 校验注解（如 @NotBlank, @Size）
• 禁止直接拼接 SQL 防止注入攻击

2. 事务管理：

• @Transactional 注解仅标注在 Service 方法上
• 避免在循环中频繁提交事务

3. 性能优化：

• 使用 @EntityGraph 预加载关联关系
• 避免在循环中执行数据库查询（批量操作优先）

代码风格规范

1. 命名规范：

• 类名：UpperCamelCase（如 UserServiceImpl）
• 方法/变量名：lowerCamelCase（如 saveUser）
• 常量：UPPER_SNAKE_CASE（如 MAX_LOGIN_ATTEMPTS）

2. 注释规范：

• 方法必须添加注释且方法级注释使用 Javadoc 格式
• 计划待完成的任务需要添加 // TODO 标记
• 存在潜在缺陷的逻辑需要添加 // FIXME 标记

3. 代码格式化：

• 使用 IntelliJ IDEA 默认的 Spring Boot 风格
• 禁止手动修改代码缩进（依赖 IDE 自动格式化）

部署规范

部署规范

• 生产环境需禁用 @EnableAutoConfiguration 的默认配置
• 敏感信息通过 application.properties 外部化配置
• 使用 Spring Profiles 管理环境差异（如 dev, prod）

扩展性设计规范

1. 接口优先：

服务层接口（UserService）与实现（UserServiceImpl）分离

2. 扩展点预留：

关键业务逻辑需提供 Strategy 或 Template 模式支持扩展

3. 日志规范：

使用 SLF4J 记录日志（禁止直接使用 System.out.println）

核心操作需记录 INFO 级别日志，异常记录 ERROR 级别

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

可以看到已经按照我们添加的异常处理规则以及编码规范进行了优化。

编辑后的灵码规则文件的的位置在项目的具体目录位置如图，如果没有看到的话刷新一下磁盘就看到了：

总的来说，通义灵码IDE 插件提供 AI 规则的设置功能，开发者可以通过设定个性化规则提示词，在智能问答和 AI 程序员中，引导模型生成更为精准、符合个人偏好或项目风格的代码与回答。