跳至主要內容

开发规范

mdp-vben 沿用了官方 vben 的工程化体系（lint 工具链、Git hooks），并在此之上增加了 mdp 的业务约定。本文分两部分：mdp 特有约定（重点）与 lint 工具链速查。

1. mdp 特有约定

1.1 硬性禁令

  • 禁止使用 TypeScript 非空断言 !（如 props.objectId!），改用条件判断或可选链：
// ❌ 禁止
const id = props.objectId!;

// ✅ 推荐
const id = props.objectId ?? '';
if (!props.objectId) return;
  • 禁止执行 git add / commit / push 等操作交给自动化工具，提交动作由开发者本人完成。

1.2 API 层写法约定

接口定义统一放在 src/api/<服务>/<模块>/ 下，按 api.ts（请求）+ model.d.ts（类型）拆分。

import type { DictType } from './model';
import type { PageParams, PageResult } from '#/api';

import { RequestEnum, ServicePrefixEnum } from '@vben/constants';

import { requestClient } from '#/api/request';

// 1. 服务前缀必须使用 ServicePrefixEnum，禁止硬编码 '/console'
const SERVICE_PREFIX = ServicePrefixEnum.CONSOLE;
const MODULAR = `${SERVICE_PREFIX}/system/dict`;

// 2. 以 namespace 导出，方法名与后端保持一致（page/list/save/update/remove/getById）
export namespace DictApi {
  /** 分页查询（分页一律 POST） */
  export const page = (params: PageParams<Partial<DictType.DictQuery>>) =>
    requestClient.post<PageResult<DictType.DictVo>>(`${MODULAR}/page`, params);

  /** 批量删除（返回是否成功） */
  export const remove = (ids: string[]) =>
    requestClient.post<boolean>(`${MODULAR}/delete`, ids);
}

要点：

  • URL 规则：/api/服务前缀/模块/表名/方法，如 /api/console/organization/user/getById；服务前缀用 ServicePrefixEnum，boot/cloud 模式的前缀处理由请求层自动完成；

  • 请求方式：分页查询用 POST，其他查询用 GET，增删改用 POST；

    没有使用PUT、DELETE等类型，应为某些政务系统或网络不支持PUT、DELETE。

  • 分页类型：入参 PageParams<Partial<XxxType.XxxQuery>>，返回 PageResult<XxxType.XxxVo>；

  • 后端统一返回：{ code, msg, data, path, extra, timestamp }，code: 0 成功，-1 系统繁忙、-2 超时、-9 参数校验异常、-10 操作异常（响应拦截器已统一处理，业务代码拿到的就是 data）。

1.3 页面与权限

  • 业务页面放在 src/views/<域>/<模块>/，菜单由后端动态下发，新增页面后需在控制台「菜单管理」中配置路由与组件路径；
  • 按钮级权限用权限码控制，权限码统一定义在各应用的 src/constants/ 下，配合 v-hasAnyPermission 或 useAccess 使用；
  • 跨应用共用的业务组件放 packages/effects/components，应用内私有的放 src/components/。

1.4 依赖管理

  • 新增依赖优先加入 pnpm catalog（pnpm-workspace.yaml），各包通过 "依赖名": "catalog:" 引用，保证全仓库版本统一；
  • 不要把业务依赖加到根 package.json，加到使用它的应用/包里。

2. lint 工具链速查

配置文件集中在 internal/lint-configs/，根目录只有入口文件：

工具作用命令
Oxfmt代码格式化（缩进、引号、尾逗号）pnpm oxfmt / pnpm oxfmt --check
OxlintJS/TS 快速检查（主力）pnpm oxlint / pnpm oxlint --fix
ESLintVue、JSONC、YAML 规则补充pnpm eslint . --cache
StylelintCSS/SCSS 检查pnpm stylelint "**/*.{vue,css,scss}" --cache
Commitlint提交信息校验提交时自动触发
Cspell拼写检查pnpm check:cspell
lefthookGit hooks 管理pnpm exec lefthook install

一键全量检查（提交 PR 前建议执行）：

pnpm check        # 循环依赖 + 依赖规范 + 类型检查 + 拼写
pnpm lint         # 格式化 + 所有 lint

2.1 Git hooks（lefthook.yml）

  • pre-commit：对暂存文件并行执行格式化与 lint（vue/js/style/md/json/package.json）；
  • commit-msg：commitlint 校验提交信息；
  • post-merge：合并后自动 pnpm install。

临时跳过校验：git commit -m 'xxx' --no-verify（仅限紧急情况）。

2.2 提交信息规范

遵循 Angular 约定：type(scope): 描述，描述使用中文：

feat(permission): 新增字段权限管理功能
fix(router): 优化异常处理避免路由无限循环
refactor(locales): 优化多处英文文本的翻译与表述

常用 type：feat / fix / style / perf / refactor / revert / test / docs / chore / types。

3. 编辑器建议

VSCode 推荐安装：ESLint、Oxc（oxlint/oxfmt 集成）、Stylelint、Code Spell Checker。仓库根目录的 vben-admin.code-workspace 已包含调试配置（三个应用分别对应 7700/7710/7720 端口）。

Copyright © 2026-present henhen6