Jeesite代码规范：团队协作开发指南-优快云博客

Jeesite代码规范：团队协作开发指南

【免费下载链接】jeesite Java rapid development platform, based (Spring Boot, Spring MVC, Apache Shiro, MyBatis, Beetl, Bootstrap, AdminLTE), online code generation, including modules: Organization, role users, menu and button authorization, data permissions, system parameters, content management, workflow, etc. Loose coupling design is adopted; one key skin switch; account security Settings, password policies; Online scheduled task configuration; Support cluster, support SAAS; Support for multiple data sources 项目地址: https://gitcode.com/gh_mirrors/jee/jeesite

引言：为什么规范比技术更重要？

你是否经历过这些场景：接手同事代码时如同破译天书，不同模块风格迥异导致维护成本激增，重构时因类型混乱引发连锁bug？Jeesite作为Java生态最成熟的快速开发平台之一，其Vue3前端架构采用Monorepo设计+TypeScript强类型体系，为团队协作提供了天然优势。本文将系统拆解Jeesite的代码规范体系，通过12个核心维度+28个实战案例，帮你的团队实现"一次编码，处处可用"的协作效率。

一、项目架构与目录规范

1.1 模块化目录结构

Jeesite采用Turborepo驱动的Monorepo架构，将代码按功能边界划分为独立包，形成"高内聚低耦合"的模块化组织：

mermaid

核心目录说明：

目录路径	功能定位	编码责任人
packages/core	全局共享组件/工具	架构师
packages/[业务模块]	业务功能模块	模块负责人
web/src	应用入口/路由配置	前端负责人
web/api	接口请求封装	全栈开发者

1.2 文件命名规范

采用"帕斯卡命名法(PascalCase)"与"短横线命名法(kebab-case)"严格区分不同类型文件：

# 正确示例
packages/core/components/Button/src/BasicButton.vue  // 组件文件
packages/core/hooks/useTable.ts                     // 钩子函数
web/api/sys/menu.ts                                 // API模块

# 错误示例
components/button/button.vue                        // 未使用帕斯卡命名
hooks/usetable.ts                                   // 未使用驼峰命名

二、编码规范核心维度

2.1 TypeScript类型规范

强制类型定义：所有变量、函数参数必须显式声明类型，禁用any类型（除非有充分理由并添加@ts-ignore说明）。

// 正确示例
interface Menu {
  menuCode?: string;
  menuName: string;  // 必填项不加?
  isShow: '0' | '1'; // 有限枚举值使用联合类型
}

// 错误示例
const getMenu = (params) => { ... } // 缺少参数类型
let menuData: any = [];             // 滥用any类型

接口设计原则：使用interface定义数据模型，type定义联合/交叉类型：

// 数据模型用interface（支持扩展）
interface User extends BaseEntity {
  userId: string;
  userName: string;
}

// 联合类型用type
type Status = 'success' | 'error' | 'loading';

2.2 Vue组件开发规范

组件封装标准：

基础组件：使用withInstall包装，确保按需引入时自动注册：

// packages/core/components/Button/index.ts
import { withInstall } from '@jeesite/core/utils';
import button from './src/BasicButton.vue';

export const Button = withInstall(button);

Props设计：采用PropType定义复杂类型，必填项必须指定required: true：

// 正确示例
import { defineProps, PropType } from 'vue';
const props = defineProps({
  size: {
    type: String as PropType<'small' | 'medium' | 'large'>,
    default: 'medium'
  },
  onClick: {
    type: Function as PropType<(e: MouseEvent) => void>,
    required: true
  }
});

组件命名：
- 基础组件：Basic[组件名]（如BasicTable）
- 业务组件：业务领域+功能（如UserForm、RoleSelect）

2.3 API接口规范

请求封装标准：统一使用defHttp工具，按业务域划分API模块：

// web/api/sys/menu.ts 示例
import { defHttp } from '@jeesite/core/utils/http/axios';

export const menuListData = (params?: Menu) =>
  defHttp.post<Menu[]>({ 
    url: '/sys/menu/listData', 
    params 
  });

接口命名约定：

查询列表：[资源]ListData（如menuListData）
表单数据：[资源]Form（如menuForm）
保存操作：[资源]Save（如menuSave）

2.4 样式规范

基于Stylelint配置，核心规则包括：

/* 正确示例 */
.component-class {
  display: flex;
  margin: 0;
  padding: 0;
}

/* 错误示例 */
.ComponentClass { /* 类名必须使用kebab-case */
  DISPLAY: flex; /* 属性名必须小写 */
  margin: 0px;   /* 数值0不允许加单位 */
}

主题变量使用：必须使用设计系统提供的Less变量，禁止硬编码颜色值：

// 正确
@primary-color: #1890ff;
.button {
  background: @primary-color;
}

// 错误
.button {
  background: #1890ff; /* 应使用变量 */
}

三、代码质量保障体系

3.1 自动化工具链

Jeesite集成完整的质量保障工具链，通过npm脚本统一调用：

// package.json 关键脚本
{
  "scripts": {
    "lint:eslint": "eslint --cache ./**/*.{ts,tsx,vue} --fix",
    "lint:stylelint": "stylelint ./**/*.{vue,less} --fix",
    "lint:prettier": "prettier --write ./**/*.{vue,ts}"
  }
}

提交前检查：建议配置husky钩子，在commit前自动执行lint检查。

3.2 代码审查清单

检查维度	检查项
功能完整性	是否实现所有需求点
类型安全	有无any类型、未使用的变量
性能	大数据列表是否使用虚拟滚动
可访问性	表单是否有label、按钮是否有明确文本

四、协作流程规范

4.1 Git工作流

推荐采用Feature Branch工作流：

从develop分支创建功能分支：feature/[功能名]
提交信息格式：[类型]: 简短描述（如feat: 添加用户导入功能）
完成后提交PR到develop分支，至少1人Code Review通过

4.2 版本号规范

遵循语义化版本：主版本.次版本.修订号

主版本：不兼容的API变更（1.0.0）
次版本：向后兼容的功能新增（0.1.0）
修订号：向后兼容的问题修复（0.0.1）

五、实战案例：从0到1开发组件

5.1 组件开发流程

mermaid

5.2 列表组件完整示例

<template>
  <BasicTable @register="registerTable">
    <!-- 表格标题 -->
    <template #tableTitle>
      <Icon icon="i-carbon:table" /> 数据列表
    </template>
    <!-- 操作列 -->
    <template #action="{ record }">
      <a-button @click="handleEdit(record)">编辑</a-button>
    </template>
  </BasicTable>
</template>

<script lang="ts" setup name="UserDataList">
import { useTable } from '@jeesite/core/hooks/web/useTable';
import { userListData } from '@/api/sys/user';

// 表格配置
const [registerTable] = useTable({
  api: userListData,
  columns: [
    {
      title: '用户名',
      dataIndex: 'userName',
      width: 180
    },
    {
      title: '状态',
      dataIndex: 'status',
      dictType: 'sys_user_status' // 使用字典
    }
  ]
});

// 编辑处理
const handleEdit = (record) => {
  // 实现编辑逻辑
};
</script>

六、规范落地与持续优化

6.1 新人培训清单

环境搭建：pnpm install && pnpm dev
规范学习：阅读本文档+《Vue风格指南》
示例参考：packages/test/views/demo目录

6.2 规范迭代机制

每季度召开规范评审会
新特性引入需同步更新规范
定期统计lint错误类型，优化规则

结语

代码规范不是束缚创造力的枷锁，而是团队协作的共同语言。Jeesite通过模块化架构+强类型系统+自动化工具，构建了可扩展的规范体系。遵循这些规范，不仅能提升代码质量，更能降低沟通成本，让团队专注于业务创新而非格式之争。

收藏本文档，转发给团队成员，一起打造工业级的前端代码库！下期预告：《Jeesite性能优化实战指南》

附录：常用命令速查

命令	功能
pnpm lint:all	执行全量代码检查
pnpm type:check	TypeScript类型检查
pnpm build	构建生产版本

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考