java的 大模型提示词 prompt ，代码规范


■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■提示词■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■开始

### 一、核心编码原则
1. 遵循SOLID设计原则，代码具备高内聚、低耦合特性，避免冗长的巨型类/方法（单个方法代码量不超过80行）。
2. 基于Spring Boot/Spring Cloud生态开发，严格区分控制层（Controller）、服务层（Service）、数据访问层（Mapper/Repository）、配置层（Config）、VO/DTO/PO层，禁止跨层调用。
3. 全程采用面向接口编程，服务层先定义接口（XXXService），再实现类（XXXServiceImpl），通过@Service/@Resource注入。

### 二、分层编码规范
#### 1. 配置层（独立配置类）
- 所有配置项（如数据源、线程池、MQ、Redis、第三方SDK等）必须独立封装为XXXConfig类，通过@Configuration注解标识。
- 配置参数优先从application.yml/application.properties读取，使用@Value或@ConfigurationProperties绑定，禁止硬编码常量。
- 示例：
/**
 * 文档权限模块 - Redis配置类
 * @author VAMA
 */
@Configuration
@ConfigurationProperties(prefix = "doc.permission.redis")
@Slf4j
public class DocumentPermissionRedisConfig {
    /** Redis缓存过期时间（秒） */
    private Integer expireSeconds = 300;
    /** Redis缓存前缀 */
    private String prefix = "doc:permission:";

    /**
     * 构建文档权限缓存Key
     * @param resourceId 资源ID
     * @param tenantId 租户ID
     * @return 拼接后的缓存Key
     */
    public String buildCollaboratorCacheKey(Long resourceId, Long tenantId) {
        return StrUtil.format("{}{}:{}", prefix, resourceId, tenantId);
    }

    // getter/setter
}

#### 2. 服务层（Service）规范
- 方法头必须包含完整的JavaDoc注释：
  - 格式：/** 【操作类型】功能描述 */ + @param 每个参数的简洁注释 + @return 返回值说明 + @throws 异常说明（如有）。
  - 操作类型统一：【查询】【新增】【修改】【删除】【批量新增】【批量修改】【批量删除】【校验】【更新】等。
- 方法内部逻辑分块注释（变量定义、参数校验、核心业务、返回结果），关键步骤添加日志（INFO级别），异常场景添加ERROR级别日志。
- 禁止在服务层捕获全局异常（统一交给全局异常处理器），但需对业务异常主动抛出（如AssertUtils断言）。
- 事务控制：涉及多表操作的方法添加@Transactional注解，明确rollbackFor属性（如@Transactional(rollbackFor = Exception.class)）。
- 示例参考：批量删除资源协作者权限的Service方法（已提供）。

/**
 * 资源可见协作者 Service 接口
 * @author VAMA
 */
public interface DocumentCollaboratorService {

    /**
     * 【更新】-批量更新资源（文件/文件夹）协作者权限（单个/批量）
     * @param reqVO 更新请求 VO
     * @return 协作者列表
     */
    Boolean batchUpdateResourceCollaboratorPermission(DocumentCollaboratorListBatchUpdateReqVO reqVO);

    /**
     * 【删除】-批量删除资源（文件/文件夹）协作者权限（单个/批量）
     * @param reqVO 删除请求 VO
     * @return 协作者列表
     */
    Boolean batchDeleteResourceCollaborator(DocumentCollaboratorListBatchDeleteReqVO reqVO);


}

 /**
     * 【删除】批量删除资源协作者权限
     * @param reqVO 更新请求 VO
     * @return 协作者列表
     */
    @Override
    public Boolean batchDeleteResourceCollaborator(DocumentCollaboratorListBatchDeleteReqVO reqVO) {
        /* *********************************变量****************************************/
        Long loginUserId = getLoginUserId();
        Long tenantId = TenantContextHolder.getTenantId();
        List<Long> userIdList = reqVO.getUserIdList();
        Integer resourceType = reqVO.getResourceType();
        Long resourceId = reqVO.getResourceId();
        log.info("[batchDeleteResourceCollaborator][【删除】批量删除资源协作者权限] loginUserId={}, tenantId={}, userIdList={}, resourceType={}, resourceId={}",
                loginUserId, tenantId, userIdList.toString(), resourceType, resourceId);
        /* *********************************校验****************************************/
        //校验-当前用户是否有管理员权限
        Boolean hasManagePermission = documentPermissionService.checkUserHasResourceManagePermission(loginUserId, resourceType, resourceId, tenantId);
        AssertUtils.isFalse(hasManagePermission, ErrorCodeConstants.DOCUMENT_ADMIN_ACCESS_DENIED);//文档管理权限不足
        //校验-判断列表中是否有管理员（管理员不可以改管理员权限）
        Boolean isExistManage = documentPermissionMapper.checkUserIdListIsExistManage(tenantId, userIdList, resourceType, resourceId);
        AssertUtils.isTrue(isExistManage, ErrorCodeConstants.DOCUMENT_PERMISSION_CANNOT_MODIFY_MANAGE);//您无法修改同级管理员的权限。如需调整，请联系创建者。
        /* *********************************业务****************************************/
        //删除-批量删除权限协作者-用户类型
        int deleteUserCount = 0;
        int deleteDeptCount = 0;
        //删除-批量删除权限协作者-用户类型
        if(CollectionUtils.isNotEmpty(reqVO.getUserIdList())){
            // 发送权限移除消息和权限审计日志
            this.sendMQPermissionRemoveAndAuditLog(resourceType,resourceId, userIdList);
            //删除权限
            deleteUserCount = documentPermissionMapper.deleteByResourceTypeAndResourceIdAndTargetTypeAndTargetIdList(
                    resourceType, resourceId, DocumentPermissionTargetTypeEnum.USER.getType(), reqVO.getUserIdList(), tenantId);

        }
        //删除-批量删除权限协作者-部门类型
        if(CollectionUtils.isNotEmpty(reqVO.getDeptIdList())){
            deleteDeptCount = documentPermissionMapper.deleteByResourceTypeAndResourceIdAndTargetTypeAndTargetIdList(
                    resourceType, resourceId, DocumentPermissionTargetTypeEnum.DEPT.getType(), reqVO.getDeptIdList(), tenantId);
        }
        log.info("[batchDeleteResourceCollaborator][【删除】批量删除资源协作者权限] deleteUserCount={},deleteDeptCount={}", deleteUserCount,deleteDeptCount );
        return true;
    }



#### 3. 控制层（Controller）规范
- 控制层仅负责接收请求、参数校验、调用服务层、返回响应，**禁止编写任何业务逻辑**。
- 类注释：/** 模块类型 - 业务模块 Controller */ + @author 信息。
- 注解规范：
  - 类级别：@RestController + @RequestMapping（根路径） + @Tag（OpenAPI标签） + @Validated + @Slf4j。
  - 方法级别：@Operation（summary标注【操作类型】功能描述） + HTTP方法注解（@GetMapping/@PostMapping等）。
- 参数校验：入参通过@Valid/@Validated注解触发JSR380校验（如@NotNull/@NotBlank/@Min等），参数类（ReqVO）字段添加校验注解和注释。
- 响应统一：所有接口返回CommonResult<T>类型，通过success()/error()方法封装响应码、响应信息、数据体，禁止直接返回原始对象。
- 示例参考：文档权限Controller（已提供）。

/**
 * 用户端 - 文档权限 Controller
 * @author VAMA
 */
@Tag(name = "用户端 - 文档权限 - 协作者")
@RestController
@RequestMapping("/doc/permission")
@Validated
@Slf4j
public class DocumentPermissionController {

    @Resource
    private DocumentPermissionService documentPermissionService;
    @Resource
    private DocumentSharingScopeService resourceSharingScopeService;
    @Resource
    private DocumentNotificationProducer documentNotificationProducer;
    @Resource
    private SystemDeptApi systemDeptApi;
    @Resource
    private DocumentCollaboratorService documentCollaboratorService;

    //-----------------------共享范围----------------------------
    @PostMapping("/query-resource-sharing-scope")
    @Operation(summary = "【查询】更新资源共享范围(文件/文件夹)")
    public CommonResult<DocumentSharingScopeQueryRespVO> queryResourceSharingScope(@Valid @RequestBody DocumentSharingScopeQueryReqVO reqVO) {
        return success(resourceSharingScopeService.queryResourceSharingScope(reqVO));
    }
	


#### 4. 数据访问层（Mapper/Repository）
- 基于MyBatis-Plus实现，Mapper接口继承BaseMapper<PO>，禁止在Mapper中编写业务逻辑。
- SQL语句优先通过XML文件编写，复杂SQL拆分，避免嵌套过深，添加字段注释。
- 分页查询统一使用IPage分页对象，禁止手写LIMIT/OFFSET。
- 示例：
/**
 * 文档权限 Mapper
 * @author VAMA
 */
@Mapper
public interface DocumentPermissionMapper extends BaseMapper<DocumentPermissionPO> {
    /**
     * 校验用户列表是否包含管理员
     * @param tenantId 租户ID
     * @param userIdList 用户ID列表
     * @param resourceType 资源类型
     * @param resourceId 资源ID
     * @return true-包含管理员，false-不包含
     */
    Boolean checkUserIdListIsExistManage(@Param("tenantId") Long tenantId, 
                                         @Param("userIdList") List<Long> userIdList,
                                         @Param("resourceType") Integer resourceType,
                                         @Param("resourceId") Long resourceId);
}

#### 5. VO/DTO/PO层规范
- 严格区分三类对象：
  - PO：数据库实体类（对应表结构），添加@TableName/@TableId/@TableField注解，字段名与数据库保持一致（下划线转驼峰）。
  - VO：视图对象（前端入参/出参），分为ReqVO（请求）/RespVO（响应），添加@Data/@NoArgsConstructor/@AllArgsConstructor注解，字段添加中文注释。
  - DTO：数据传输对象（服务层内部传输），用于多表联查/复杂数据组装。
- 示例：
/**
 * 批量删除资源协作者请求 VO
 * @author VAMA
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class DocumentCollaboratorListBatchDeleteReqVO {
    /** 资源ID */
    @NotNull(message = "资源ID不能为空")
    private Long resourceId;
    /** 资源类型（1-文件，2-文件夹） */
    @NotNull(message = "资源类型不能为空")
    private Integer resourceType;
    /** 用户ID列表 */
    private List<Long> userIdList;
    /** 部门ID列表 */
    private List<Long> deptIdList;
}

### 三、接口设计规范（RESTful风格强化）
1. 接口路径命名：
   - 全部使用小写字母，多单词用短横线（-）分隔，如/ doc/permission/query-resource-sharing-scope。
   - 路径仅包含资源名词，不包含动词，通过HTTP方法表达操作：
     - GET：查询（单个/列表），如GET /doc/permission/collaborator/{resourceId}（查询指定资源的协作者）。
     - POST：新增/提交，如POST /doc/permission/collaborator（新增协作者）。
     - PUT：全量更新，如PUT /doc/permission/collaborator（更新协作者全部信息）。
     - PATCH：部分更新，如PATCH /doc/permission/collaborator/{userId}（修改指定用户的权限）。
     - DELETE：删除，如DELETE /doc/permission/collaborator/batch（批量删除协作者）。
2. 版本控制：接口版本通过路径（/v1/doc/permission）或请求头（X-API-Version: v1）区分，禁止在接口名中加版本号。
3. 分页参数：统一使用pageNum（页码，默认1）、pageSize（页大小，默认10）作为请求参数，响应包含total（总条数）、list（数据列表）。
4. 响应码规范：
   - 200：请求成功。
   - 400：参数错误。
   - 401：未登录/Token过期。
   - 403：权限不足。
   - 404：资源不存在。
   - 500：服务器内部错误。

### 四、通用编码规范
1. 注释规范：
   - 类注释：必须包含功能描述、作者，可选版本、创建时间。
   - 方法注释：必须包含功能描述、参数说明、返回值说明，异常场景添加@throws。
   - 字段注释：PO/VO/DTO的字段必须添加中文注释，说明字段含义。
   - 禁用无用注释（如// TODO、// 此处省略代码等）。
2. 异常处理：
   - 自定义业务异常（BusinessException），统一通过全局异常处理器（@RestControllerAdvice）捕获。
   - 禁止使用try-catch捕获所有异常，仅捕获明确需要处理的异常（如IO异常、第三方接口调用异常）。
   - 异常信息必须包含上下文（如用户ID、资源ID），便于排查问题。
3. 日志规范：
   - 统一使用Slf4j（@Slf4j），禁止使用System.out.println。
   - 日志格式：[方法名][操作描述] 关键字段1={}, 关键字段2={}。
   - 日志级别：DEBUG（调试）、INFO（正常流程）、WARN（警告）、ERROR（异常），生产环境禁用DEBUG级别。
4. 命名规范：
   - 类名：大驼峰（PascalCase），如DocumentPermissionService。
   - 方法名/变量名：小驼峰（camelCase），如batchDeleteResourceCollaborator。
   - 常量：全大写，下划线分隔，如ERROR_CODE_CONSTANTS.DOCUMENT_ADMIN_ACCESS_DENIED。
   - 包名：全小写，如com.vama.doc.permission.controller。
5. 其他：
   - 禁止使用魔法值（如数字1/2、字符串"user"），统一封装为枚举（Enum）或常量类。
   - 集合操作必须判空（使用CollectionUtils.isEmpty/NotEmpty），避免空指针异常。
   - 数据库操作必须考虑租户隔离（TenantContextHolder），所有SQL添加tenant_id条件。
   - 接口入参必须通过@Valid/@Validated校验，禁止在服务层重复校验（特殊场景除外）。
6.忽略CommonResult ， 和 全局异常处理器 的编写过程


■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■提示词■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■结束