1 环境信息
- 操作系统：windows 10
- AI 编程工具：Claude Code 2.0.42
- 模型信息
- GLM-4.7：国内官网，Coding Plan 套餐。
- MiniMax-M2.1：国外官网，Coding Plan 套餐。
2 结论先行
2.1 评分汇总
| 场景 | 模型 | 技术栈识别 | 架构理解深度 | 规范完整性 | 输出专业性 | 实用性 | 总分 |
|---|---|---|---|---|---|---|---|
| 后端：NestJS+TypeScript+Fastify | MiniMax-M2.1 | 5 | 5 | 5 | 5 | 5 | 25 |
| GLM-4.7 | 5 | 5 | 5 | 5 | 5 | 25 | |
| 后端：Java+Spring Boot2 | MiniMax-M2.1 | 4 | 3 | 3 | 3 | 3 | 16 |
| GLM-4.7 | 5 | 5 | 5 | 5 | 5 | 25 | |
| 前端：Vue3+TypeScript+Vite | MiniMax-M2.1 | 5 | 5 | 5 | 5 | 5 | 25 |
| GLM-4.7 | 5 | 5 | 5 | 4 | 5 | 24 |
2.2 模型特性总结
2.2.1 MiniMax-M2.1
- 结构化输出：层次分明，易于快速理解和实施
- 规范明确：提供清晰的命名、格式、组织规范
- 实用性强：侧重可操作性和实施细节
- 深度有限：在复杂架构和设计原则阐述上相对薄弱
- 不一致性：不同场景表现差异较大（Java场景较弱）
改进建议
- 加强复杂场景（如Java企业级）的深度分析
- 提升架构理念和设计原则的阐述能力
2.2.2 GLM-4.7
- 架构深度：深入阐述设计原则、分层架构、最佳实践
- 全面性：覆盖开发全生命周期规范
- 一致性：各场景表现稳定且优秀
- 工程思维：体现企业级开发理念和工程化思考
- 结构略冗：部分输出内容可进一步精简优化
改进建议
- 优化输出结构，提升可读性和实施效率
- 保持现有优势，继续加强实用性示例
2.3 场景选择建议
| 项目类型 | 推荐模型 | 理由 |
|---|---|---|
| 快速原型/标准化项目 | MiniMax-M2.1 | 结构清晰，便于快速实施 |
| 复杂企业级系统 | GLM-4.7 | 架构理解深入，规范全面 |
| Java生态项目 | GLM-4.7 | 在Java场景表现显著更优 |
| 前端Vue项目 | 根据需求： • 快速实施→MiniMax • 架构深度→GLM | 二者各有优势 |
| 全栈项目指导 | GLM-4.7 | 表现更稳定全面 |
3 后端
提示词：输出工程用到的技术栈/代码结构，并提供编程规范
3.1 评价标准
| 维度 | 5分标准 | 3分标准 | 1分标准 |
|---|---|---|---|
| 技术栈识别 | 准确识别全部核心技术栈及开发工具链 | 识别主要技术栈，遗漏部分工具 | 技术栈识别不全或有错误 |
| 架构理解深度 | 详细描述分层架构、设计模式、模块组织 | 基本描述结构，缺乏深度分析 | 架构描述模糊或错误 |
| 规范完整性 | 覆盖编码、测试、部署等完整开发规范 | 涵盖基本规范，细节不完整 | 规范描述零散不系统 |
| 输出专业性 | 技术术语准确，架构理念先进，体现工程思维 | 技术描述基本正确，缺乏深度 | 技术理解肤浅或有错误 |
| 实用性 | 提供具体配置、代码示例和最佳实践 | 有概念描述但缺乏实施细节 | 缺乏可操作 |
3.2 技术栈：NestJS+TypeScript+Fastify
3.2.1 评测结果
二者均表现优秀，无明显差距。GLM-4.7在架构理念和设计原则阐述上略胜一筹。
3.2.1.1 MiniMax-M2.1
得分：25
| 维度 | 评分 | 评价理由 |
|---|---|---|
| 技术栈识别 | 5 | 完整列出核心与辅助技术栈，版本清晰，涵盖工具链 |
| 架构理解深度 | 5 | 详细描述分层架构、模块组织、设计模式（如MVC、Repository） |
| 规范完整性 | 5 | 覆盖编码、命名、API设计、数据库、Git提交等完整规范 |
| 输出专业性 | 5 | 术语准确，结构清晰，体现企业级工程思维 |
| 实用性 | 5 | 提供具体配置、命令、代码示例、模块结构模板 |
3.2.1.2 GLM-4.7
得分：25
| 维度 | 评分 | 评价理由 |
|---|---|---|
| 技术栈识别 | 5 | 技术栈识别完整，分类清晰，版本齐全 |
| 架构理解深度 | 5 | 详细描述分层、实体设计、生命周期、控制器规范等 |
| 规范完整性 | 5 | 覆盖编码、注释、异常、查询、日志、事务等全方位规范 |
| 输出专业性 | 5 | 术语专业，架构理念先进，设计原则明确（如SOLID） |
| 实用性 | 5 | 提供完整代码示例、配置说明、开发命令、设计原则 |
3.2.2 模型输出结果
3.2.2.1 MiniMax-M2.1
yaml
Backend 技术栈与代码结构
---
一、技术栈
| 分类 | 技术/版本 | 说明 |
|----------|-------------------------------------|--------------------------------------|
| 运行时 | Node.js | TypeScript 编译执行环境 |
| 框架 | NestJS v11 | Node.js 企业级后端框架 |
| Web 框架 | Fastify v5.4 | 高性能 HTTP 服务器 |
| ORM | Prisma v6.9 | 数据库 ORM 框架（SQLite/PostgreSQL） |
| 认证 | Passport + JWT | 身份认证中间件 |
| 验证 | class-validator + class-transformer | DTO 校验与转换 |
| 文档 | Swagger/NestJS Swagger | API 文档自动生成 |
| 日志 | Winston + Winston Daily Rotate | 日志管理与轮转 |
| 指标 | prom-client + @nestjs/terminus | 应用健康监控 |
| 配置 | YAML + ConfigService | 配置文件管理 |
| 工具库 | Lodash、bcrypt、qs、zod | 辅助工具 |
| 构建 | TypeScript + SWC | TS 编译与构建 |
| 测试 | Jest + Supertest | 单元测试与 E2E 测试 |
| 代码规范 | ESLint + Prettier | 代码格式化与检查 |
---
二、代码结构
backend/
├── src/
│ ├── main.ts # 应用入口
│ ├── app.module.ts # 根模块
│ ├── config/ # 配置文件
│ │ └── config.yml # 主配置（数据库、端口、日志等）
│ ├── commons/ # 公共模块
│ │ ├── auth/ # 认证授权（JWT/Basic、Guards、Decorators）
│ │ ├── config/ # 配置实体类
│ │ ├── database/ # Prisma 服务封装
│ │ ├── entity/ # 基础实体类（StandardEntity、CreateEntity 等）
│ │ ├── exception/ # 异常处理（BusinessException、ErrorCode）
│ │ ├── log/ # 日志模块
│ │ ├── query/ # 分页查询（QueryFilter、QueryResult）
│ │ ├── util/ # 工具类（日期、密码加密）
│ │ └── web/ # Web 通用（拦截器、过滤器）
│ └── modules/ # 业务模块
│ ├── admin/ # 管理员模块
│ ├── auth/ # 登录认证模块
│ ├── attendance/ # 考勤管理模块
│ ├── course/ # 课程管理模块
│ ├── operationlog/ # 操作日志模块
│ ├── option/ # 配置选项模块
│ ├── student/ # 学生管理模块
│ ├── teacher/ # 教师管理模块
│ └── user/ # 用户管理模块
├── prisma/
│ ├── schema.prisma # 数据模型定义
│ ├── schema.prisma.sqlite # SQLite 配置
│ ├── schema.prisma.postgresql # PostgreSQL 配置
│ └── seed.ts # 数据填充脚本
├── test/ # 测试文件
├── package.json
├── tsconfig.json
├── .prettierrc
├── eslint.config.mjs
└── Dockerfile
---
三、模块标准结构
每个业务模块遵循统一结构：
modules/{module}/
├── {module}.module.ts # 模块定义
├── {module}.controller.ts # API 控制器
├── {module}.service.ts # 业务逻辑层
├── {module}.repository.ts # 数据访问层（可选）
├── dto/ # 数据传输对象
│ ├── {module}.create.dto.ts
│ ├── {module}.update.dto.ts
│ └── {module}.query.dto.ts
└── entity/ # 实体类
├── {module}.entity.ts
├── {module}.queryfilter.ts
└── {module}.querydecoder.ts
---
四、编程规范
4.1 代码风格
| 配置项 | 值 |
|--------|---------------------|
| 缩进 | 2 空格 |
| 引号 | 单引号 ' ' |
| 分号 | 必须使用 ; |
| 尾逗号 | all（对象、数组等） |
| 行宽 | 80 字符 |
4.2 ESLint 规则
- @typescript-eslint/no-explicit-any: off（允许使用 any）
- @typescript-eslint/no-floating-promises: warn
- @typescript-eslint/no-unsafe-*:: warn
- prettier/prettier: error
4.3 命名规范
| 类型 | 规范 | 示例 |
|------------|------------------|-------------------------------------------|
| 文件名 | kebab-case | course.controller.ts |
| 类名 | PascalCase | CourseController、CourseService |
| 变量/函数 | camelCase | courseService、findById |
| 常量 | UPPER_SNAKE_CASE | MAX_RETRY_COUNT |
| 数据库字段 | snake_case | created_at、user_id |
| DTO 属性 | camelCase | courseId（内部）→ course_id（数据库映射） |
| 枚举 | PascalCase | UserType、CourseType |
4.4 模块分层规范
Controller (API 层)
↓ 调用
Service (业务逻辑层)
↓ 调用
Repository (数据访问层)
↓ 调用
Prisma (数据库操作)
4.5 API 设计规范
- 路由前缀: 全局通过 config.yml 配置（默认 /api）
- 请求方式: 统一使用 POST（Body 传参）
- 响应格式: 统一 ResponseDto<T> 结构
- 分页: 使用 QueryResult<T> 包装
- 认证: @UseGuards(JwtAuthGuard, RolesGuard)
- 角色控制: @Roles(UserType.admin)
4.6 数据库规范
- 字段映射使用 @map() 注解
- 必须添加索引 @index()
- 软删除使用 isActive 布尔字段
- 审计字段: creatorId/Name、updatorId/Name、createdAt、updatedAt
4.7 Git 提交规范
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式（不影响功能）
refactor: 重构
test: 测试相关
chore: 构建/工具/依赖更新
---
五、常用命令
# 开发启动
npm run start:dev
# 代码检查
npm run lint
# 代码格式化
npm run format
# Prisma 操作
npm run prisma:generate # 生成客户端
npm run prisma:migrate # 迁移数据库
npm run prisma:studio # 可视化数据库
npm run prisma:seed # 填充数据
# 构建与运行
npm run build
npm run start:prod
---
六、配置说明
backend/src/config/config.yml 主要配置项：
app:
contextPath: /api # 全局路由前缀
port: 3000 # 监听端口
compression:
enabled: true
threshold: 1024
database:
provider: sqlite # sqlite / postgresql
url: prisma/local.db
jwt:
secret: your-secret
expiresIn: 1h
swagger:
enabled: true
title: Course System API
path: swagger3.2.2.2 GLM-4.7
typescript
📦 Backend 工程技术栈
核心框架
| 技术 | 版本 | 用途 |
|------------|---------|--------------------------------------|
| NestJS | ^11.0.1 | 渐进式Node.js框架，提供完整的MVC架构 |
| Fastify | ^5.4.0 | 高性能Web服务器（替代Express） |
| TypeScript | ^5.7.3 | 类型安全的开发语言 |
数据层
| 技术 | 版本 | 用途 |
|----------------|--------|--------------------------------------|
| Prisma | ^6.9.0 | 类型安全的ORM，支持SQLite/PostgreSQL |
| @prisma/client | ^6.9.0 | Prisma查询客户端 |
认证与安全
| 技术 | 版本 | 用途 |
|------------------|---------|---------------|
| @nestjs/passport | ^11.0.5 | 认证策略集成 |
| @nestjs/jwt | ^11.0.0 | JWT令牌处理 |
| passport-jwt | ^4.0.1 | JWT认证策略 |
| passport-http | ^0.3.0 | Basic认证策略 |
| bcrypt | ^6.0.0 | 密码哈希加密 |
日志与监控
| 技术 | 版本 | 用途 |
|---------------------------|---------|--------------------|
| winston | ^3.17.0 | 日志记录 |
| winston-daily-rotate-file | ^5.0.0 | 日志文件按日期轮转 |
| @nestjs/terminus | ^11.0.0 | 健康检查 |
| prom-client | ^15.1.3 | Prometheus指标采集 |
API文档与验证
| 技术 | 版本 | 用途 |
|-------------------|---------|---------------------|
| @nestjs/swagger | ^11.2.0 | OpenAPI/Swagger文档 |
| class-validator | ^0.14.2 | DTO声明式验证 |
| class-transformer | ^0.5.1 | 对象转换 |
其他工具
| 技术 | 版本 | 用途 |
|-------------|----------|----------------|
| compression | ^1.8.1 | HTTP响应压缩 |
| nestjs-cls | ^6.0.1 | 请求上下文管理 |
| lodash | ^4.17.21 | 工具函数库 |
| uuid | ^11.1.0 | UUID生成 |
| zod | ^4.1.5 | 运行时类型验证 |
---
🏗️ 代码结构
目录架构
backend/
├── prisma/ # 数据库层
│ ├── schema.prisma # 数据模型定义
│ └── seed.ts # 种子数据
│
├── src/
│ ├── main.ts # 应用入口
│ ├── app.module.ts # 根模块
│ │
│ ├── commons/ # 公共模块（跨业务）
│ │ ├── auth/ # 认证授权
│ │ │ ├── decorator/ # 装饰器（@JwtAuth, @Public等）
│ │ │ ├── guard/ # 守卫
│ │ │ ├── strategy/ # Passport策略
│ │ │ └── jwt-auth.service.ts
│ │ │
│ │ ├── config/ # 配置管理
│ │ ├── database/ # 数据库服务
│ │ ├── entity/ # 公共实体基类
│ │ ├── exception/ # 异常处理
│ │ ├── log/ # 日志服务
│ │ ├── query/ # 查询封装
│ │ ├── util/ # 工具类
│ │ └── web/ # Web层组件
│ │ ├── filter/ # 异常过滤器
│ │ ├── interceptor/ # 拦截器
│ │ └── management/ # 管理端点
│ │
│ └── modules/ # 业务模块
│ ├── user/ # 用户模块
│ ├── course/ # 课程模块
│ ├── attendance/ # 考勤模块
│ ├── auth/ # 认证控制器
│ ├── admin/ # 管理员
│ ├── student/ # 学生
│ ├── teacher/ # 教师
│ └── operationlog/ # 操作日志
│
├── test/ # 测试目录
└── docs/ # 项目文档
模块标准结构
每个业务模块遵循统一的分层架构：
module-name/
├── module-name.controller.ts # 控制器层（路由、参数验证）
├── module-name.service.ts # 服务层（业务逻辑）
├── module-name.repository.ts # 仓储层（数据访问）
├── module-name.module.ts # 模块定义（依赖注入）
├── dto/ # 数据传输对象（API请求/响应）
│ ├── module-create.dto.ts
│ ├── module-update.dto.ts
│ └── module.dto.ts
└── entity/ # 实体类（领域模型）
├── module.entity.ts
├── module.queryfilter.ts # 查询过滤器
└── module.querydecoder.ts # 查询解码器
数据模型
| 模型 | 说明 | 关键字段 |
|------------------|----------------------------|----------------------------------------------------------------------|
| User | 用户表（管理员/教师/学生） | id, name, username, password, userType, isActive |
| Course | 课程表 | id, name, courseType, isActive, studentCount |
| CourseTeacher | 课程-教师关联 | courseId, teacherId |
| CourseStudent | 课程-学生关联 | courseId, studentId, totalSessions, usedSessions, startDate, endDate |
| AttendanceRecord | 考勤记录 | courseId, studentId, attendanceDate, sessionsConsumed |
| OperationLog | 操作日志 | id, module, operation, operatorId |
---
📋 编程规范
1. TypeScript配置规范
编译选项 (tsconfig.json):
- 目标版本: ES2023
- 模块系统: CommonJS
- 装饰器支持: 启用 experimentalDecorators
- 严格模式: strictNullChecks: true
- 源码映射: 启用 sourceMap
2. 代码风格规范
Prettier配置 (.prettierrc):
{
"singleQuote": true, // 使用单引号
"tabWidth": 2, // 缩进2空格
"printWidth": 80, // 每行最大80字符
"semi": true, // 使用分号
"trailingComma": "all" // 尾随逗号
}
ESLint规则 (eslint.config.mjs):
- 关闭 @typescript-eslint/no-explicit-any（允许any）
- 浮动Promise警告
- 不安全操作警告（参数/成员访问/赋值）
- Prettier集成
3. 命名规范
| 类型 | 规范 | 示例 |
|----------|-------------------------|---------------------------------------|
| 文件名 | kebab-case | course.service.ts, user-create.dto.ts |
| 类名 | PascalCase | CourseService, UserCreateDto |
| 方法名 | camelCase | findById, listUnAssignedTeachers |
| 接口名 | PascalCase，无I前缀 | QueryDecoder, Converter |
| 常量 | UPPER_SNAKE_CASE | CourseType.session_card |
| 私有成员 | camelCase，无下划线前缀 | private courseRepository |
4. 注释规范
/**
* 创建课程
* @param createCourseDto 创建DTO
* @param operateContext 操作上下文
* @returns 课程实体
*/
async create(
createCourseDto: CourseCreateDto,
operateContext: OperateContext,
): Promise<CourseEntity>
要求：
- 所有公开方法必须有JSDoc注释
- 复杂逻辑必须添加行内注释
- 注释使用中文简体
5. 实体设计规范
继承体系：
Entity (基础实体)
└── StandardEntity (标准实体，含审计字段)
└── CourseCreateEntity, UserCreateEntity等
审计字段（继承自 StandardEntity）:
createdAt: Date; // 创建时间
creatorId: string; // 创建人ID
creatorName: string; // 创建人姓名
updatedAt: Date; // 更新时间
updatorId: string; // 更新人ID
updatorName: string; // 更新人姓名
生命周期方法：
- onCreated(operateContext): 创建时调用
- onUpdated(operateContext): 更新时调用
6. 控制器规范
装饰器顺序：
@Controller('route') // 1. 路由定义
@UseGuards(JwtAuthGuard, RolesGuard) // 2. 守卫
@Roles(UserType.admin) // 3. 角色控制
async methodName() { } // 4. 方法实现
依赖注入：
constructor(
private readonly courseService: CourseService,
private readonly userService: UserService,
) {}
7. 服务层规范
异常处理：
- 资源不存在：throw new NotFoundException('资源不存在')
- 冲突：throw new ConflictException('资源已存在')
- 参数错误：throw new BadRequestException('参数错误')
操作模式：
// 1. 验证
const exists = await this.repository.existsByName(name);
if (exists) {
throw new ConflictException('名称已存在');
}
// 2. 转换DTO为Entity
const entity = new CourseCreateEntity(dto);
entity.onCreated(operateContext);
// 3. 持久化
return await this.repository.create(entity);
8. 查询规范
查询过滤器 (QueryFilter):
{
page: 1,
pageSize: 10,
keyword?: string,
isActive?: boolean,
sorts?: [{ field: string, direction: 'asc'|'desc' }]
}
查询结果 (QueryResult<T>):
{
records: T[],
page: number,
pageSize: number,
total: number
}
9. 认证授权规范
认证方式：
- Basic Auth: 管理员获取初始Token
- JWT Bearer: 标准API调用
- Refresh Token: 刷新访问令牌
角色类型 (UserType):
- admin: 管理员（完全权限）
- teacher: 教师（课程相关权限）
- student: 学生（只读权限）
使用方式：
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(UserType.admin)
async adminOnlyMethod() { }
@AccessContext() operateContext: OperateContext // 获取当前操作人
10. 日志规范
日志级别：
- error: 错误，需要立即处理
- warn: 警告，需要关注
- info: 一般信息
- debug: 调试信息
日志轮转：按日期自动轮转，文件名格式：application-YYYY-MM-DD.log
---
🔧 开发命令
# 开发模式（热重载）
npm run start:dev
# 生产构建
npm run build
npm run start:prod
# 数据库操作
npm run prisma:generate # 生成Prisma客户端
npm run prisma:migrate # 执行迁移
npm run prisma:seed # 填充种子数据
npm run prisma:studio # 打开数据库管理界面
# 代码质量
npm run lint # ESLint检查
npm run format # Prettier格式化
# 测试
npm run test # 单元测试
npm run test:e2e # 端到端测试
npm run test:cov # 测试覆盖率
---
📝 核心设计原则
1. 单一职责: 每个类只负责一个功能领域
2. 依赖注入: 使用NestJS的DI容器管理依赖
3. 分层架构: Controller → Service → Repository 清晰分离
4. 实体转换: DTO ↔ Entity ↔ PO 分层转换
5. 审计追踪: 所有写操作自动记录创建人/更新人
6. 异常统一: 使用NestJS内置异常，统一错误处理
7. 类型安全: 全链路TypeScript类型检查3.3 技术栈：Java+Spring Boot2
3.3.1 评测结果
GLM-4.7在Java项目理解深度、规范完整性和实用性上明显优于MiniMax-M2.1。
3.3.1.1 MiniMax-M2.1
得分：16
| 维度 | 评分 | 评价理由 |
|---|---|---|
| 技术栈识别 | 4 | 列出主要技术栈，但部分组件（如MyBatis细节、监控工具）描述较简 |
| 架构理解深度 | 3 | 描述基本结构，缺乏深度分层和设计模式分析 |
| 规范完整性 | 3 | 涵盖基础规范，但缺乏异常处理、事务、日志等细节 |
| 输出专业性 | 3 | 描述基本正确，但缺乏架构理念和工程思维体现 |
| 实用性 | 3 | 有项目结构和基本命令，但缺少具体代码示例和最佳实践 |
3.3.1.2 GLM-4.7
得分：25
| 维度 | 评分 | 评价理由 |
|---|---|---|
| 技术栈识别 | 5 | 完整识别技术栈，包括基础设施组件和监控工具 |
| 架构理解深度 | 5 | 详细描述分层架构、模块职责、依赖注入、外部服务调用等 |
| 规范完整性 | 5 | 覆盖异常、事务、日志、配置、注释、SOLID原则等完整规范 |
| 输出专业性 | 5 | 术语准确，架构清晰，体现企业级开发理念 |
| 实用性 | 5 | 提供详细代码示例、配置说明、开发原则和检查清单 |
3.3.2 模型输出结果
3.3.2.1 MiniMax-M2.1
typescript
LAB-PROJECT 项目技术栈与编程规范
一、项目概述
| 项目属性 | 说明 |
|----------|--------------------------------------------|
| 项目名称 | 同三方协作平台的对接服务 |
| 项目简称 | lab |
| 版本 | 1.13-SNAPSHOT |
| 项目类型 | 多模块 Maven 项目 |
| GitLab | https://xx/LAB/lab.git |
---
二、技术栈
2.1 后端技术栈
| 技术 | 版本/说明 | 用途 |
|------------------------|-----------|------------------|
| Java | 1.8 | 编程语言 |
| Spring Boot | - | 应用框架核心 |
| Spring Cloud OpenFeign | - | 声明式HTTP客户端 |
| Tomcat Embedded | 9.0.69 | 内嵌Web容器 |
| MyBatis/Custom-DAO | - | 数据访问层 |
| Oracle JDBC | ojdbc6 | 数据库驱动 |
| Druid | - | 数据库连接池 |
| Custom | 2.15 | 个人服务框架 |
| custom-Commons | 2.x | 个人公共组件库 |
| Logback | 1.2.11 | 日志框架 |
| Lombok | - | 代码简化 |
2.2 API文档
| 技术 | 用途 |
|-------------------|----------------|
| Swagger/Springfox | API接口文档 |
| Knife4j | Swagger UI增强 |
2.3 个人基础设施组件
| 组件 | 用途 |
|------------------|------------------------------|
| custom-event | 事件调用（消息队列可靠投递） |
| custom-rdb-version | 数据库版本管理 |
| custom-micrometer | 指标监控（Prometheus） |
| custom-job | 定时任务调度 |
| custom-sequence | 分布式序列号生成 |
| custom-snowflake | 雪花算法ID生成 |
---
三、项目模块结构
lab (父POM)
├── pom.xml
├── lab-api # 对外服务接口对象
│ └── src/main/java/com/custom/lab/api/
│ └── domain/ # 领域对象定义
├── lab-core # 服务数据访问层
│ └── src/main/java/com/custom/lab/
│ ├── commons/ # 公共组件
│ ├── domain/ # 业务领域
│ │ ├── config/
│ │ ├── department/
│ │ ├── feishu/
│ │ ├── message/
│ │ ├── orgUser/
│ │ ├── store/
│ │ └── user/
│ └── feishu/ # 飞书客户端
├── lab-service # 对外服务实现（Spring Boot主模块）
│ ├── src/main/java/com/custom/lab/
│ │ ├── Application.java # 启动类
│ │ ├── config/
│ │ ├── domain/
│ │ ├── feishu/
│ │ ├── web/
│ │ ├── wecom/
│ │ └── health/
│ └── src/main/resources/
│ ├── application.yml
│ ├── logback.xml
│ └── public/ # 静态资源
├── lab-rdb-scripts # 数据库安装脚本
├── lab-rdb-setup # 数据库安装程序
└── lab-rdb-upgrade # 数据库升级程序
---
四、代码分层架构
Controller层 (REST API)
↓
Service层 (业务逻辑)
↓
Repository/DAO层 (数据访问)
↓
数据库 (Oracle)
---
五、编程规范
5.1 文件头版权声明
/**
* 版权所有(C)，个人所有，2021，所有权利保留。
* <p>
* 项目名： lab
* 文件名： 文件名.java
* 模块说明：
* 修改历史：
* 2022年05月18日 - zhangsan - 创建。
*/
5.2 包命名规范
// 基础包结构
com.custom.lab.{模块名}
// 示例
com.custom.lab.domain.department
com.custom.lab.feishu
com.custom.lab.wecom
5.3 类命名规范
| 类型 | 规范 | 示例 |
|----------|-------------------|---------------------------|
| 实体类 | 简单名词 | Department, User |
| 服务接口 | {模块}Service | DepartmentService |
| 服务实现 | {模块}ServiceImpl | UserOperLogServiceImpl |
| 控制器 | {模块}Controller | FeiShuController |
| 常量类 | {模块}Constants | - |
5.4 方法命名规范
| 类型 | 规范 | 示例 |
|----------|-----------------|-------------------------|
| 获取单个 | getBy{Field} | getBy(String code) |
| 保存 | save | save(Department dept) |
| 删除 | delete | delete(Department dept) |
| 查询列表 | query 或 getAll | query(Filter filter) |
5.5 Controller 规范
@Slf4j
@Api(tags = FeiShuController.TAG)
@RestController
@RequestMapping("/v1/feishu")
public class FeiShuController {
public static final String TAG = "飞书";
@ApiOperation(value = "接口描述")
@PostMapping(value = "/login")
public Response<LoginResult> login(@RequestBody RequestDTO request) {
// ...
return Response.success(result);
}
}
规范要点：
- 使用 @Api 和 @ApiOperation 注解
- 路径使用 RESTful 风格：/v1/{platform}/{resource}
- 返回统一使用 Response<T> 包装
- 使用 @Slf4j 打印日志
5.6 实体类规范
@Data
@EqualsAndHashCode(callSuper = true)
public class Department extends Entity {
@ApiModelProperty("部门代码")
private String code;
@ApiModelProperty("部门名称")
private String name;
}
规范要点：
- 使用 Lombok @Data、@EqualsAndHashCode(callSuper = true)
- 继承 Entity 基类
- 字段使用 @ApiModelProperty 注释
- 不使用 @Data 注解时手动添加 toString()
5.7 异常处理
// Service 层抛出异常
void save(Department department) throws CustomServiceException;
// 异常类型
com.custom.exception.CustomServiceException
5.8 日志规范
@Slf4j
public class SomeService {
public void doSomething() {
log.info("开始处理...");
log.debug("详细参数: {}", param);
log.error("错误信息", exception);
}
}
5.9 配置规范
# application.yml 注释风格
#==========================================================
# 应用服务器配置
#==========================================================
server:
port: 8080 # 服务运行端口
---
六、API 响应规范
// 成功响应
return Response.success(result);
// 失败响应（使用 CustomServiceException）
throw new CustomServiceException("错误描述");
---
七、Git 提交规范
项目使用 Conventional Commits 标准，提交信息格式：
<type>(<scope>): <subject>
# 示例
feat(feishu): 增加飞书登录功能
fix(department): 修复部门同步bug
docs: 更新README
---
八、相关文档
| 文档路径 | 内容 |
|--------------------------------|----------|
| doc/design/飞书对接设计文档.md | 设计文档 |
| doc/devops/部署配置说明.md | 部署配置 |
| doc/faq/FAQ.md | 常见问题 |
| README.md | 项目概述 |
---
九、关键配置
| 配置项 | 值 |
|-------------|------------------------|
| 服务端口 | 8080 |
| 监控端口 | 8081 |
| 上下文路径 | /lab-service |
| API文档地址 | /lab-service/doc.html |
| 默认环境 | prd |3.3.2.2 GLM-4.7
java
根据代码库分析，我为你整理了完整的技术栈、代码结构和编程规范：
---
📊 技术栈概览
核心框架
| 技术 | 版本 | 用途 |
|------------------------|--------|------------------|
| Spring Boot | 2.x | 应用框架 |
| lab | 2.15 | 个人应用开发框架 |
| custom | 多组件 | 企业组件库 |
| Spring Cloud OpenFeign | - | REST客户端 |
| Lombok | - | 代码简化 |
持久层与数据库
- Spring JDBC + Druid 连接池
- Oracle (主要) / MySQL / PostgreSQL
- custom RDB 数据库版本管理
监控与文档
- Swagger/Knife4j - API文档
- Micrometer/Prometheus - 监控指标
- Logback - 日志框架
---
🏗️ 代码结构
lab/
├── lab-api/ # API接口对象层
│ └── domain/ # 领域对象定义
│
├── lab-core/ # 核心业务层
│ ├── commons/ # 公共工具(JDBC等)
│ ├── domain/ # 领域服务
│ │ ├── department/ # 部门管理
│ │ ├── feishu/ # 飞书集成
│ │ ├── wecom/ # 企业微信
│ │ ├── user/ # 用户管理
│ │ └── store/ # 门店管理
│ └── feishu/ # 飞书业务服务
│
├── lab-service/ # Web服务层(主应用)
│ ├── config/ # Spring配置
│ ├── domain/ # 服务实现
│ ├── feishu/ # 飞书控制器
│ ├── wecom/ # 企业微信控制器
│ └── Application.java # 启动类
│
└── pom.xml # Maven父POM
分层原则：
1. lab-api - 对外接口定义，无业务逻辑
2. lab-core - 核心业务 + 数据访问
3. lab-service - Web层，仅处理HTTP请求/响应
---
📐 编程规范
4. 包命名规范
com.custom.lab
├── domain.{feature} # 领域对象
│ ├── repository/ # 数据访问层
│ └── service/ # 领域服务
├── commons # 公共工具
├── config # 配置类
└── {platform} # 平台控制器(feishu/wecom)
示例：
// ✅ 正确
com.custom.lab.domain.user.repository.UserRepository
com.custom.lab.domain.user.service.UserService
com.custom.lab.feishu.FeiShuController
// ❌ 错误
com.custom.lab.user.UserDao
com.custom.UserController
---
5. 领域对象设计规范
实体类位置
| 类型 | 位置 | 说明 |
|------------|-------------------|------------|
| 领域实体 | lab-api/domain/ | 跨模块共享 |
| 数据库实体 | lab-core/domain/ | 持久化专用 |
实体类规范
// ✅ 推荐：使用Lombok简化
@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class DUser implements Serializable {
private String uuid;
private String name;
private String orgUuid;
// 领域行为
public boolean isActive() {
return StringUtils.isNotBlank(uuid);
}
}
// ❌ 避免：过多的DTO转换层
---
6. 分层设计原则
三层架构职责
// ========== lab-service (Web层) ==========
@RestController
@RequestMapping("/v1/feishu")
public class FeiShuController {
@Autowired
private UserService userService; // 仅调用领域服务
// ✅ 仅处理HTTP请求/响应，无业务逻辑
@PostMapping("/login")
public Result<LoginResult> login(@RequestBody LoginRequest request) {
LoginResult result = userService.login(request.getCode());
return Result.success(result);
}
}
// ========== lab-core (领域层) ==========
@Service
public class UserServiceImpl implements UserService {
@Autowired
private UserRepository userRepository; // 数据访问
@Autowired
private FeiShuClient feiShuClient; // 外部服务
// ✅ 业务逻辑核心
@Override
@Transactional
public LoginResult login(String code) {
// 1. 调用飞书认证
FeiShuUser fsUser = feiShuClient.getUserInfo(code);
// 2. 查询或创建用户
DUser user = userRepository.findByUuid(fsUser.getUuid());
if (user == null) {
user = createUserFromFeiShu(fsUser);
userRepository.save(user);
}
// 3. 生成令牌
return generateLoginResult(user);
}
}
// ========== lab-core (数据访问层) ==========
@Repository
public class UserRepositoryImpl implements UserRepository {
@Autowired
private JdbcTemplate jdbcTemplate;
// ✅ 仅负责数据CRUD
@Override
public DUser findByUuid(String uuid) {
String sql = "SELECT * FROM d_user WHERE uuid = ?";
return jdbcTemplate.queryForObject(sql, new UserRowMapper(), uuid);
}
}
---
7. 异常处理规范
// ========== 自定义业务异常 ==========
public class labException extends RuntimeException {
private final String code;
public labException(String code, String message) {
super(message);
this.code = code;
}
}
// ========== 全局异常处理 ==========
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(labException.class)
public Result<Void> handlelabException(labException e) {
log.warn("业务异常: {}", e.getMessage());
return Result.fail(e.getCode(), e.getMessage());
}
@ExceptionHandler(Exception.class)
public Result<Void> handleException(Exception e) {
log.error("系统异常", e);
return Result.fail("SYSTEM_ERROR", "系统异常，请联系管理员");
}
}
// ========== 使用示例 ==========
// ✅ 明确抛出业务异常
if (user == null) {
throw new labException("USER_NOT_FOUND", "用户不存在");
}
---
8. 外部服务调用规范
// ========== Feign客户端定义 ==========
@FeignClient(
name = "feishu-api",
url = "${feishu.api-url}",
configuration = FeiShuFeignConfig.class
)
public interface FeiShuClient {
@GetMapping("/open-apis/user/v4/info")
FeiShuUserResponse getUserInfo(@RequestHeader("Authorization") String token);
@PostMapping("/open-apis/contact/v3/users/batch_get")
FeiShuUserBatchResponse batchGetUsers(@RequestBody FeiShuUserBatchRequest request);
}
// ========== 配置类 ==========
@Configuration
public class FeiShuFeignConfig {
@Bean
public RequestInterceptor authInterceptor(@Value("${feishu.app-id}") String appId,
@Value("${feishu.app-secret}") String appSecret) {
return template -> {
String token = getAccessToken(appId, appSecret);
template.header("Authorization", "Bearer " + token);
};
}
@Bean
public Logger.Level feignLoggerLevel() {
return Logger.Level.BASIC; // 生产环境使用BASIC或NONE
}
}
// ✅ 调用时添加重试和降级
@Retryable(value = {FeignException.class}, maxAttempts = 3)
public FeiShuUser getUserFromFeiShu(String userId) {
try {
return feiShuClient.getUserInfo(userId);
} catch (FeignException e) {
log.error("调用飞书API失败", e);
throw new labException("FEISHU_API_ERROR", "获取飞书用户信息失败");
}
}
---
9. 数据库操作规范
// ✅ 使用JdbcTemplate + RowMapper
@Repository
public class UserRepositoryImpl implements UserRepository {
private final JdbcTemplate jdbcTemplate;
private static final String SQL_BY_UUID =
"SELECT uuid, name, org_uuid FROM d_user WHERE uuid = ?";
@Override
public DUser findByUuid(String uuid) {
List<DUser> users = jdbcTemplate.query(
SQL_BY_UUID,
new UserRowMapper(),
uuid
);
return users.isEmpty() ? null : users.get(0);
}
// ✅ RowMapper作为静态内部类
private static class UserRowMapper implements RowMapper<DUser> {
@Override
public DUser mapRow(ResultSet rs, int rowNum) throws SQLException {
DUser user = new DUser();
user.setUuid(rs.getString("uuid"));
user.setName(rs.getString("name"));
user.setOrgUuid(rs.getString("org_uuid"));
return user;
}
}
}
// ✅ 使用custom JDBC扩展（如果可用）
@Autowired
private CustomJdbcTemplate customJdbcTemplate;
public List<DUser> findByOrg(String orgUuid) {
return customJdbcTemplate.query(
"SELECT * FROM d_user WHERE org_uuid = :orgUuid",
Map.of("orgUuid", orgUuid),
new UserRowMapper()
);
}
---
10. 配置管理规范
# ========== application.yml 结构 ==========
spring:
application:
name: lab-service
datasource:
url: ${DB_URL:jdbc:oracle:thin:@localhost:1521:db}
username: ${DB_USER:user}
password: ${DB_PASSWORD:pwd}
type: com.alibaba.druid.pool.DruidDataSource
feishu:
api-url: https://open.feishu.cn
app-id: ${FEISHU_APP_ID}
app-secret: ${FEISHU_APP_SECRET}
encrypt-key: ${FEISHU_ENCRYPT_KEY}
wecom:
api-url: https://qyapi.weixin.qq.com
corp-id: ${WECOM_CORP_ID}
secret: ${WECOM_SECRET}
# ========== 配置属性类 ==========
@ConfigurationProperties(prefix = "feishu")
@Validated
@Getter
@Setter
public class FeiShuProperties {
@NotBlank
private String apiUrl;
@NotBlank
private String appId;
@NotBlank
private String appSecret;
private String encryptKey;
}
---
11. 日志规范
// ========== 使用Slf4j ==========
@Slf4j
@Service
public class UserServiceImpl {
// ✅ 记录关键业务流程
public LoginResult login(String code) {
log.info("用户登录开始, code={}", code);
try {
FeiShuUser fsUser = feiShuClient.getUserInfo(code);
log.info("获取飞书用户成功, uuid={}", fsUser.getUserId());
// ... 业务逻辑
log.info("用户登录成功, uuid={}", user.getUuid());
return result;
} catch (Exception e) {
log.error("用户登录失败, code={}, error={}", code, e.getMessage(), e);
throw new labException("LOGIN_FAILED", "登录失败");
}
}
}
// ========== 日志级别规范 ==========
// ERROR: 系统错误、需要立即关注的异常
// WARN: 业务异常、重试操作
// INFO: 关键业务流程（登录、同步等）
// DEBUG: 开发调试信息（生产环境关闭）
---
12. 事务管理规范
@Service
@Transactional // ✅ 类级别默认只读事务
public class DepartmentServiceImpl implements DepartmentService {
// ✅ 只读操作
@Transactional(readOnly = true)
public Department findByUuid(String uuid) {
return departmentRepository.findByUuid(uuid);
}
// ✅ 写操作明确指定
@Transactional(readOnly = false, rollbackFor = Exception.class)
public void syncDepartment(FeiShuDepartment fsDept) {
Department dept = convertToDepartment(fsDept);
departmentRepository.save(dept);
// 同步子部门
fsDept.getChildren().forEach(this::syncDepartment);
}
// ✅ 避免长事务，大数据量分批处理
@Transactional
public void syncAllDepartments() {
int pageSize = 100;
int page = 0;
List<FeiShuDepartment> batch;
do {
batch = feiShuClient.fetchDepartments(page, pageSize);
batch.forEach(this::syncDepartment);
page++;
} while (!batch.isEmpty());
}
}
---
13. 代码注释规范
/**
* 用户服务实现
*
* <p>主要职责：</p>
* <ul>
* <li>用户登录认证（飞书/企业微信）</li>
* <li>用户信息同步</li>
* <li>平台账号管理</li>
* </ul>
*
* @author zhangsan
* @since 1.0
*/
@Slf4j
@Service
public class UserServiceImpl implements UserService {
/**
* 用户登录
*
* @param code 第三方平台授权码
* @return 登录结果（包含令牌和用户信息）
* @throws labException 当认证失败或用户不存在时抛出
*/
@Override
public LoginResult login(String code) {
// 实现代码...
}
}
// ✅ 单行注释说明复杂逻辑
// 检查用户状态：已禁用的用户不允许登录
if (user.getStatus() == UserStatus.DISABLED) {
throw new labException("USER_DISABLED", "用户已被禁用");
}
---
11. SOLID原则实践
// ========== S: 单一职责 ==========
// ✅ 每个Service只负责一个领域
@Service
public class UserService { } // 用户管理
@Service
public class DepartmentService { } // 部门管理
@Service
public class StoreService { } // 门店管理
// ❌ 避免大而全的服务
// @Service
// public class ManagementService { } // 包含所有管理逻辑
// ========== O: 开闭原则 ==========
// ✅ 使用接口 + 策略模式扩展
public interface PlatformClient {
PlatformUser getUserInfo(String code);
}
@Component("feishu")
public class FeiShuClient implements PlatformClient { }
@Component("wecom")
public class WeComClient implements PlatformClient { }
// ========== D: 依赖倒置 ==========
// ✅ 依赖抽象而非具体实现
@Service
public class UserServiceImpl {
private final UserRepository userRepository; // 接口
@Autowired
public UserServiceImpl(UserRepository userRepository) {
this.userRepository = userRepository;
}
}
---
🎯 关键开发原则
| 原则 | 实践要点 |
|------------|---------------------------------------|
| KISS | 每个方法不超过50行，职责单一 |
| DRY | 重复代码提取到 commons 工具类 |
| YAGNI | 不预留"未来可能用到"的接口和字段 |
| 防御式编程 | 所有外部输入（参数、API响应）必须校验 |
---
📝 检查清单
在提交代码前，确保：
- 所有公共方法都有Javadoc注释
- 异常处理不吞没错误，记录日志
- 外部服务调用有超时和重试机制
- 数据库操作使用PreparedStatement防止SQL注入
- 敏感信息通过配置中心注入，不硬编码
- 事务边界清晰，长事务拆分
- 日志级别正确，生产环境不输出DEBUG日志
- 单元测试覆盖核心业务逻辑4 前端
技术栈：Vu3+TypeScript+Vite工程 提示词：输出工程 frontend 用到的技术栈/代码结构，并提供编程规范
4.1 评价标准
| 维度 | 5分标准 | 3分标准 | 1分标准 |
|---|---|---|---|
| 技术栈识别 | 准确识别全部核心技术栈及开发工具链 | 识别主要技术栈，遗漏部分工具 | 技术栈识别不全或有错误 |
| 代码结构理解 | 详细描述目录结构，体现架构设计思想 | 基本描述结构，缺乏深度分析 | 结构描述模糊或错误 |
| 编程规范完整性 | 覆盖命名、格式、组件、API等完整规范 | 涵盖基本规范，细节不完整 | 规范描述零散不系统 |
| 输出可读性 | 层次分明，逻辑清晰，便于理解实施 | 结构基本清晰，部分内容冗长 | 组织混乱，难以阅读 |
| 实用性 | 提供具体配置示例和最佳实践 | 有代码示例但缺乏配置细节 | 缺乏可操作内容 |
4.2 评测结果
二者均表现优秀，MiniMax-M2.1在输出结构清晰度上略优，GLM-4.7在内容深度和原则阐述上更全面。
4.2.1 MiniMax-M2.1
得分：25
| 维度 | 评分 | 评价理由 |
|---|---|---|
| 技术栈识别 | 5 | 完整列出核心与辅助技术栈，版本清晰 |
| 代码结构理解 | 5 | 详细描述目录结构、模块划分、组件组织 |
| 编程规范完整性 | 5 | 覆盖命名、格式、组件、API、路由、状态管理等完整规范 |
| 输出可读性 | 5 | 结构清晰，层次分明，便于理解与实施 |
| 实用性 | 5 | 提供具体配置、代码示例、模块模板、常用命令 |
4.2.2 GLM-4.7
得分：24
| 维度 | 评分 | 评价理由 |
|---|---|---|
| 技术栈识别 | 5 | 技术栈识别完整，分类清晰，版本齐全 |
| 代码结构理解 | 5 | 详细描述模块化结构、分层架构、路径别名等 |
| 编程规范完整性 | 5 | 覆盖命名、样式、TypeScript、Vue组件、API、状态管理等完整规范 |
| 输出可读性 | 4 | 结构清晰，但部分内容略显冗长 |
| 实用性 | 5 | 提供完整配置示例、最佳实践、开发原则和命令速查 |
4.3 模型输出结果
4.3.1 MiniMax-M2.1
python
Frontend 技术栈、代码结构与编程规范
一、技术栈
| 分类 | 技术 | 版本 |
|-------------|-------------------|---------|
| 构建工具 | Vite | ^7.1.2 |
| 框架 | Vue 3 | ^3.5.18 |
| 语言 | TypeScript | ~5.8.3 |
| 状态管理 | Pinia | ^3.0.3 |
| 路由 | Vue Router | ^4.5.1 |
| UI 组件库 | Element Plus | ^2.11.1 |
| 图表 | ECharts | ^6.0.0 |
| HTTP 客户端 | Axios | ^1.11.0 |
| 样式 | Tailwind CSS | ^4.1.13 |
| 表单验证 | Zod | ^4.1.1 |
| 代码检查 | ESLint + Prettier | - |
---
二、代码结构
frontend/
├── src/
│ ├── main.ts # 应用入口
│ ├── App.vue # 根组件
│ ├── router/ # 路由配置
│ │ └── index.ts
│ ├── components/ # 公共组件
│ │ ├── DataTable.vue # 通用数据表格（支持分页、移动端卡片视图）
│ │ ├── ActionButton.vue # 操作按钮
│ │ ├── ActionButtonGroup.vue # 按钮组
│ │ ├── SearchForm.vue # 搜索表单
│ │ ├── DynamicFormDialog.vue # 动态表单弹窗
│ │ ├── BatchOperationDialog.vue # 批量操作弹窗
│ │ ├── Sidebar.vue # 侧边栏
│ │ ├── AppHeader.vue # 顶部栏
│ │ ├── AppLayout.vue # 布局容器
│ │ ├── MobileBottomNav.vue # 移动端底部导航
│ │ ├── StatCard.vue # 统计卡片
│ │ ├── PageHeader.vue # 页面头部
│ │ └── index.ts # 组件导出
│ ├── composables/ # 组合式函数
│ │ └── useResponsive.ts # 响应式判断（移动端/桌面端）
│ ├── utils/ # 工具函数
│ │ ├── api.util.ts # API 封装
│ │ ├── date.util.ts # 日期处理
│ │ ├── course.util.ts # 课程相关
│ │ └── mobile.ts # 移动端工具
│ ├── model/ # 公共模型
│ │ ├── api-response.model.ts # API 响应结构
│ │ ├── api-query-filter.model.ts # 查询参数
│ │ ├── api-query-result.model.ts # 分页结果
│ │ └── api-id-name.model.ts # ID-名称映射
│ ├── modules/ # 业务模块（按角色/功能划分）
│ │ ├── admin/ # 管理员模块
│ │ │ ├── api/ # API 接口
│ │ │ ├── model/ # 数据模型
│ │ │ ├── views/ # 页面组件
│ │ │ │ ├── AdminLayout.vue
│ │ │ │ ├── Dashboard.vue
│ │ │ │ ├── SystemSettings.vue
│ │ │ │ └── ...
│ │ │ └── [业务模块]/
│ │ │ ├── api/
│ │ │ ├── model/
│ │ │ └── views/
│ │ ├── teacher/ # 教师模块
│ │ │ └── ...
│ │ ├── student/ # 学生模块
│ │ │ └── ...
│ │ └── system/ # 系统模块
│ │ ├── api/
│ │ ├── model/
│ │ ├── store/ # Pinia Store
│ │ │ └── auth.ts # 认证状态
│ │ └── views/
│ │ ├── Login.vue
│ │ ├── Profile.vue
│ │ ├── 403.vue
│ │ └── 404.vue
│ └── styles/ # 全局样式
│ └── index.css # Tailwind CSS 入口
├── index.html
├── vite.config.ts # Vite 配置
├── tsconfig.json # TypeScript 配置
├── .prettierrc # Prettier 配置
├── eslint.config.ts # ESLint 配置
└── package.json
模块结构规范
modules/[角色]/ # 如 admin、teacher、student
├── api/ # API 接口（API 类封装）
│ └── [业务].api.ts
├── model/ # 数据模型
│ ├── [业务].model.ts # 实体模型
│ ├── [业务]-create.model.ts # 创建参数
│ ├── [业务]-update.model.ts # 更新参数
│ └── [业务].queryfilter.model.ts # 查询筛选参数
└── views/ # 页面组件
├── [角色]Layout.vue # 布局组件
├── [角色]Dashboard.vue # 首页
└── [业务]/
└── [业务]Management.vue
---
三、编程规范
3.1 代码风格
| 配置项 | 值 |
|--------|------------------------|
| 引号 | 单引号 ' |
| 缩进 | 2 空格 |
| 行宽 | 80 字符 |
| 分号 | 使用 ; |
| 尾逗号 | all (包括对象、数组等) |
3.2 ESLint 规则
// eslint.config.ts 关键规则
{
rules: {
'@typescript-eslint/no-explicit-any': 'off', // 允许 any（用于泛型场景）
'@typescript-eslint/no-floating-promises': 'warn',
'@typescript-eslint/no-unsafe-argument': 'warn',
'@typescript-eslint/no-unsafe-member-access': 'warn',
'@typescript-eslint/no-unsafe-assignment': 'warn',
'prettier/prettier': ['error', {
endOfLine: 'auto',
trailingComma: 'all'
}],
},
}
3.3 TypeScript 配置
{
"compilerOptions": {
"strict": true, // 严格模式
"noUnusedLocals": false, // 允许未使用的局部变量
"noUnusedParameters": false, // 允许未使用的参数
"noFallthroughCasesInSwitch": true,
"forceConsistentCasingInFileNames": true
}
}
3.4 Vue 组件规范
组件命名：
- 使用 PascalCase 命名（如 DataTable.vue、UserManagement.vue）
Script Setup 语法：
<script setup lang="ts">
// 导入顺序：Vue API → 公共组件 → 公共工具 → 业务模块
import { ref, computed, watch } from 'vue';
import DataTable from '@/components/DataTable.vue';
import { ApiUtil } from '@/utils/api.util';
import type { UserModel } from '../model/user.model';
// Props 定义
interface Props {
title?: string;
data?: UserModel[];
}
const props = withDefaults(defineProps<Props>(), {
title: '',
data: () => [],
});
// Emits 定义
const emit = defineEmits<{
'update': [data: UserModel];
'delete': [id: number];
}>();
// 组件暴露方法
defineExpose({
refresh,
resetAndRefresh,
});
</script>
3.5 API 层规范
// src/modules/admin/api/admin.api.ts
import { ApiUtil } from '@/utils/api.util';
import type { ApiResponse } from '@/model/api-response.model';
import type { AdminDashboardStatsModel } from '../model/admin-dashboard-stats.model';
/**
* 管理员端API接口
*/
export class AdminApi {
/**
* 获取管理员端首页统计数据
* @returns 统计数据
*/
static async getDashboardStats(): Promise<
ApiResponse<AdminDashboardStatsModel>
> {
return ApiUtil.post<AdminDashboardStatsModel>('/admin/dashboard/stats');
}
}
规范要点：
- 使用静态类方法（Static Class Pattern）
- 每个业务模块一个 API 类
- 方法添加 JSDoc 注释
- 返回 ApiResponse<T> 类型
3.6 模型定义规范
// src/modules/admin/model/user.model.ts
/**
* 用户实体模型
*/
export interface UserModel {
/** 用户ID */
id: number;
/** 用户名 */
username: string;
/** 真实姓名 */
realName: string;
/** 邮箱 */
email: string;
/** 用户类型: admin=管理员, teacher=教师, student=学生 */
userType: 'admin' | 'teacher' | 'student';
/** 创建时间 */
createdAt: string;
/** 更新时间 */
updatedAt: string;
}
/**
* 用户查询筛选参数
*/
export interface UserQueryFilterModel {
/** 搜索关键词（匹配用户名、姓名） */
keyword?: string;
/** 用户类型筛选 */
userType?: 'admin' | 'teacher' | 'student';
/** 页码（从1开始） */
page?: number;
/** 每页数量 */
pageSize?: number;
}
3.7 路由规范
// src/router/index.ts
const routes: RouteRecordRaw[] = [
{
path: '/admin',
name: 'AdminLayout',
component: () => import('../modules/admin/views/AdminLayout.vue'),
meta: {
requiresAuth: true,
roles: ['admin'],
title: '管理员工作台',
},
children: [
{
path: 'dashboard',
name: 'AdminDashboard',
component: () => import('../modules/admin/views/Dashboard.vue'),
meta: {
title: '工作台',
},
},
// ...
],
},
];
规范要点：
- 使用路由懒加载
- meta.requiresAuth: 是否需要认证
- meta.roles: 角色权限控制
- meta.title: 页面标题
3.8 导入路径别名
// vite.config.ts 配置
resolve: {
alias: {
'@': resolve(__dirname, 'src'),
},
}
// 使用示例
import { ApiUtil } from '@/utils/api.util';
import UserModel from '@/modules/admin/model/user.model';
---
四、常用命令
| 命令 | 说明 |
|-----------------|------------------------------|
| npm run dev | 启动开发服务器 |
| npm run build | 构建生产版本（包含类型检查） |
| npm run preview | 预览生产构建 |
---
五、核心特性
1. 响应式适配：useResponsive composable 自动检测移动端/桌面端，组件自动适配
2. API 统一封装：ApiUtil 封装 axios，统一处理请求/响应
3. 数据表格：通用 DataTable 组件支持分页、批量操作、移动端卡片视图
4. 状态持久化：Pinia + pinia-plugin-persistedstate 持久化存储认证状态
5. Element Plus 自动导入：通过 unplugin-vue-components 自动按需加载组件4.3.2 GLM-4.7
ini
📋 Frontend 工程技术栈与编程规范
一、技术栈概览
1.1 核心框架
| 技术 | 版本 | 用途 |
|------------|--------|----------------------------------------------|
| Vue 3 | 3.5.18 | 渐进式 JavaScript 框架，使用 Composition API |
| TypeScript | 5.8.3 | 类型安全，开启严格模式 |
| Vite | 7.1.2 | 新一代前端构建工具 |
1.2 路由与状态管理
| 技术 | 版本 | 用途 |
|-----------------------------|-------|-----------------------------|
| Vue Router | 4.5.1 | 官方路由管理器（Hash 模式） |
| Pinia | 3.0.3 | 官方状态管理库 |
| pinia-plugin-persistedstate | 4.5.0 | 状态持久化 |
1.3 UI 框架
| 技术 | 版本 | 用途 |
|-------------------------|--------|--------------------------|
| Element Plus | 2.11.1 | Vue 3 组件库（自动导入） |
| @element-plus/icons-vue | 2.3.2 | 图标库 |
| Tailwind CSS | 4.1.13 | 原子化 CSS 框架 |
| ECharts | 6.0.0 | 数据可视化图表库 |
1.4 HTTP 客户端
| 技术 | 版本 | 用途 |
|-------|--------|----------------------------------------|
| Axios | 1.11.0 | HTTP 请求库，封装了拦截器和 Token 刷新 |
1.5 工具库
| 技术 | 版本 | 用途 |
|-----------|---------|---------------------------|
| lodash-es | 4.17.21 | JavaScript 工具库 |
| zod | 4.1.1 | TypeScript 优先的模式验证 |
| js-base64 | 3.7.8 | Base64 编解码 |
1.6 代码质量工具
| 工具 | 版本 | 配置 |
|-------------------|--------|--------------------------------|
| ESLint | 9.34.0 | 扁平配置，支持 Vue/TS/JSON/CSS |
| Prettier | 3.6.2 | 代码格式化 |
| typescript-eslint | 8.40.0 | TypeScript ESLint 支持 |
1.7 开发增强
| 插件 | 版本 | 作用 |
|-------------------------|--------|-------------------------------|
| unplugin-auto-import | 20.0.0 | 自动导入 Vue/Router/Pinia API |
| unplugin-vue-components | 29.0.0 | 自动导入组件 |
---
二、代码结构
2.1 目录树
frontend/
├── src/
│ ├── components/ # 公共组件
│ ├── composables/ # 组合式函数
│ ├── model/ # 全局数据模型
│ ├── modules/ # 业务模块（按角色划分）
│ │ ├── admin/ # 管理员模块
│ │ ├── student/ # 学生模块
│ │ ├── teacher/ # 教师模块
│ │ └── system/ # 系统模块（认证、个人资料等）
│ ├── router/ # 路由配置
│ ├── styles/ # 全局样式
│ ├── utils/ # 工具函数
│ ├── assets/ # 静态资源
│ ├── App.vue # 根组件
│ └── main.ts # 入口文件
├── public/ # 公共静态文件
└── 配置文件
2.2 模块化结构规范
每个业务模块遵循以下结构：
modules/{module-name}/
├── api/ # API 请求层
├── model/ # 数据模型/类型定义
├── views/ # 页面组件
├── components/ # 模块专属组件（可选）
└── store/ # Pinia 状态管理（可选）
示例：
modules/admin/course/
├── api/
│ └── course.api.ts
├── model/
│ ├── course.model.ts
│ ├── course-create.model.ts
│ ├── course-update.model.ts
│ └── course.queryfilter.model.ts
└── views/
└── CourseListView.vue
2.3 分层架构
Views (页面层)
↓
Components (组件层)
↓
API (接口层)
↓
Axios (HTTP 层)
↓
Backend
---
三、配置规范
3.1 TypeScript 配置
{
"compilerOptions": {
"strict": true,
"noUnusedLocals": false,
"noUnusedParameters": false,
"noFallthroughCasesInSwitch": true,
"forceConsistentCasingInFileNames": true,
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
3.2 Prettier 配置
{
"singleQuote": true, // 使用单引号
"tabWidth": 2, // 缩进 2 空格
"printWidth": 80, // 每行最大 80 字符
"semi": true, // 语句末尾加分号
"trailingComma": "all" // 尾随逗号
}
3.3 ESLint 规则
{
rules: {
'@typescript-eslint/no-explicit-any': 'off',
'@typescript-eslint/no-floating-promises': 'warn',
'@typescript-eslint/no-unsafe-argument': 'warn',
'@typescript-eslint/no-unsafe-member-access': 'warn',
'@typescript-eslint/no-unsafe-assignment': 'warn',
}
}
3.4 路径别名
- @/* 映射到 src/*
- 示例：import { foo } from '@/utils/api.util'
3.5 构建配置
{
base: '/course/', // 部署子路径
plugins: [
vue(),
tailwindcss(),
AutoImport({ resolvers: [ElementPlusResolver()] }),
Components({ resolvers: [ElementPlusResolver()] })
]
}
---
四、编程规范
4.1 文件命名规范
| 类型 | 规范 | 示例 |
|-----------------|-------------------|------------------|
| Vue 组件 | PascalCase + .vue | UserList.vue |
| TypeScript 文件 | camelCase + .ts | api.util.ts |
| 模型文件 | {name}.model.ts | course.model.ts |
| API 文件 | {name}.api.ts | course.api.ts |
| 组合式函数 | use{Purpose}.ts | useResponsive.ts |
4.2 代码风格
缩进与空格
- 使用 2 空格缩进（不使用 Tab）
- 运算符前后加空格：a + b
- 逗号后加空格：fn(a, b, c)
引号
- 优先使用单引号：const name = 'John'
- JSON 或包含单引号的字符串使用双引号
分号
- 语句末尾必须加分号
####尾随逗号
- 对象/数组/函数参数添加尾随逗号：
const obj = {
a: 1,
b: 2,
};
行宽
- 每行最多 80 字符
4.3 TypeScript 规范
类型定义
// ✅ 使用 interface 定义对象类型
export interface ApiResponse<T = any> {
success: boolean;
data?: T;
message?: string;
code?: string;
}
// ✅ 使用 type 定义联合类型或工具类型
export type UserRole = 'admin' | 'teacher' | 'student';
// ✅ 泛型约束
export function query<T>(params: QueryFilter): Promise<ApiResponse<T>> {
return ApiUtil.post('/query', params);
}
避免 any
// ❌ 避免使用 any
function processData(data: any) { }
// ✅ 使用 unknown 或具体类型
function processData(data: unknown) {
if (typeof data === 'string') { }
}
类型导入
// ✅ 使用 type 关键字导入类型
import type { ApiResponse } from '@/model/api-response.model';
import { ApiUtil } from '@/utils/api.util';
4.4 Vue 3 组件规范
使用 <script setup>
<script setup lang="ts">
import { ref, computed } from 'vue';
// 响应式状态
const count = ref(0);
const doubled = computed(() => count.value * 2);
// 方法
function increment() {
count.value++;
}
</script>
<template>
<div>{{ count }} × 2 = {{ doubled }}</div>
</template>
Props 定义
<script setup lang="ts">
interface Props {
title: string;
count?: number;
}
// 使用 withDefaults 设置默认值
const props = withDefaults(defineProps<Props>(), {
count: 0,
});
</script>
Emits 定义
<script setup lang="ts">
const emit = defineEmits<{
update: [value: string];
delete: [id: string];
}>();
</script>
4.5 API 调用规范
API 模块组织
// src/modules/{module}/api/{name}.api.ts
import { ApiUtil } from '@/utils/api.util';
import type { ApiResponse } from '@/model/api-response.model';
import type { CourseModel } from '../model/course.model';
export const courseApi = {
/**
* 查询课程列表
*/
query: (params?: CourseQueryFilterModel): Promise<ApiResponse<ApiQueryResult<CourseModel>>> => {
return ApiUtil.post('/course/query', params);
},
/**
* 根据ID获取课程详情
*/
getById: (id: string): Promise<ApiResponse<CourseModel>> => {
return ApiUtil.post('/course/getById', { id });
},
/**
* 创建课程
*/
create: (data: CourseCreateModel): Promise<ApiResponse<CourseModel>> => {
return ApiUtil.post('/course/create', data);
},
/**
* 更新课程
*/
update: (data: Partial<CourseUpdateModel>): Promise<ApiResponse<CourseModel>> => {
return ApiUtil.post('/course/update', data);
},
/**
* 删除课程
*/
delete: (data: { id: string }): Promise<ApiResponse<void>> => {
return ApiUtil.post('/course/delete', data);
},
};
统一响应格式
export interface ApiResponse<T = any> {
success: boolean;
data?: T;
message?: string;
code?: string;
}
4.6 路由规范
路由结构
/admin/* → 管理员模块
/teacher/* → 教师模块
/student/* → 学生模块
/login → 登录页
路由守卫
- 认证检查：未登录跳转登录页
- 角色验证：根据用户角色限制访问
- 自动重定向：登录后跳转到原目标页面
4.7 状态管理规范
Pinia Store 结构
// src/modules/system/store/auth.ts
import { defineStore } from 'pinia';
import { ref, computed } from 'vue';
export const useAuthStore = defineStore('auth', () => {
// State
const accessToken = ref<string | null>(null);
const refreshToken = ref<string | null>(null);
const user = ref<UserModel | null>(null);
// Getters
const isAuthenticated = computed(() => !!accessToken.value);
const isAdmin = computed(() => user.value?.role === 'admin');
// Actions
async function login(credentials: LoginModel) { }
async function logout() { }
async function checkAuth() { }
return {
accessToken,
refreshToken,
user,
isAuthenticated,
isAdmin,
login,
logout,
checkAuth,
};
}, {
persist: true, // 持久化配置
});
4.8 注释规范
JSDoc 注释
/**
* 查询课程列表
* @param params - 查询过滤条件
* @returns 课程列表响应
*/
query: (params?: CourseQueryFilterModel): Promise<ApiResponse<ApiQueryResult<CourseModel>>> => {
return ApiUtil.post('/course/query', params);
}
组件注释
/**
* 通用数据表格组件
* 支持桌面端和移动端双视图
*
* @example
* <DataTable :data="courses" :columns="columns" />
*/
4.9 组件命名规范
公共组件
- 位置：src/components/
- 命名：PascalCase
- 示例：DataTable.vue, SearchForm.vue
业务模块组件
- 位置：src/modules/{module}/components/
- 命名：PascalCase + 模块前缀（可选）
- 示例：AdminUserForm.vue, StudentCourseCard.vue
4.10 样式规范
优先级
1. Tailwind CSS 工具类（原子化）
2. Element Plus 组件样式
3. 全局样式 (src/styles/)
4. 组件 scoped 样式
样式写法
<template>
<div class="p-4 bg-white rounded-lg shadow">内容</div>
</template>
<style scoped>
/* 组件特定样式 */
.custom-style {
/* ... */
}
</style>
---
五、最佳实践
5.1 SOLID 原则应用
S - 单一职责
- 每个组件/函数只做一件事
- API 层只负责请求，不处理业务逻辑
O - 开闭原则
- 使用 Props 和 Slots 扩展组件功能
- 避免直接修改第三方库
L - 里氏替换
- 子组件可替换父组件使用
I - 接口隔离
- Props 接口专一，避免冗余属性
D - 依赖倒置
- 依赖抽象（接口）而非具体实现
5.2 DRY（杜绝重复）
// ❌ 重复代码
function getCourses() { return ApiUtil.post('/course/query'); }
function getStudents() { return ApiUtil.post('/student/query'); }
// ✅ 抽象通用逻辑
function createQueryApi(endpoint: string) {
return (params?: any) => ApiUtil.post(`/${endpoint}/query`, params);
}
5.3 KISS（简单至上）
// ❌ 过度复杂
const result = data.reduce((acc, item) => {
return item.active ? [...acc, item] : acc;
}, []);
// ✅ 简单直观
const result = data.filter(item => item.active);
5.4 YAGNI（精益求精）
- 只实现当前需要的功能
- 不要为未来预留
- 删除未使用的代码和依赖
---
六、命令速查
# 安装依赖
npm install
# 启动开发服务器
npm run dev
# 类型检查
npm run type-check
# 代码检查
npm run lint
# 格式化代码
npm run format
# 构建生产版本
npm run build
---
七、关键特性总结
| 特性 | 说明 |
|----------------|-----------------------------------|
| 模块化架构 | 按角色和业务模块清晰划分 |
| 严格类型系统 | TypeScript strict 模式 |
| 自动导入 | 组件和 API 自动导入，无需手动引入 |
| 移动端适配 | 响应式设计 + 触摸手势支持 |
| 统一 API 规范 | 标准化的 CRUD 操作 |
| 多角色权限 | Admin/Teacher/Student 三级路由 |
| Token 自动刷新 | 无感刷新认证机制 |
| 代码质量保证 | ESLint + Prettier 自动检查 |
---
以上规范基于现有代码库分析总结，遵循了 SOLID、KISS、DRY、YAGNI 原则，适合企业级团队协作开发。