命名约定

提示

严格来说，“命名约定”应该是“代码规范”中的内容，但是由于命名约定比较重要，所以单独拿出来撰文。

通用命名规则

• 变量和函数采用驼峰命名法（camelCase）。
• 常量采用大写字母和下划线命名法（UPPER_CASE）。
• 类名采用大驼峰命名法（PascalCase）。
• 避免使用缩写，使用完整名称提高可读性。

特殊命名约定

下文将详细说明项目中使用的特殊命名约定。

类型声明

• 函数入参如果是对象，其类型声明采用 ParamsFuncName 的命名方式，比如：ParamsGetUserInfo。
• 函数返回值如果是对象，其类型声明采用 ReturnFuncName 的命名方式，比如：ReturnGetUserInfo。
• 函数返回值如果是数组，其类型声明采用 ReturnFuncNameItem[] 的命名方式，比如：ReturnGetUserInfoItem[]。

TypeScript 提示

一些常见的类型声明辅助方法定义在了 typings/utils.d.ts 中。

zod 定义的 schema

采用 sName 的命名方式，比如：sGetUserInfo。其中最前面固定的 s 表示英文的单词 Schema。

举个例子：

import { zodPageQueryCommon } from "#scripts/zodUtils";

// 查询待办项列表（不含已标记删除的项目）
export const sQueryTodoList = zod.object({
  status: zod
    .union([zod.literal("0"), zod.literal("1"), zod.literal("2")])
    .optional(),
  keyword: zod.string().optional(),
  type: zod.union([zod.literal("todo"), zod.literal("goal")]).optional(),
  archived: zod.union([zod.literal("0"), zod.literal("1")]).optional(),
  ...zodPageQueryCommon,
});

控制器方法

控制器方法的名词采用 cName 的命名方式，比如：cGetUserInfo。其中最前面固定的 c 表示英文的单词 Controller。

举个例子：

import * as zod from "zod";
import { logger } from "#scripts/LogUtils";

// 更新待办项
export const sUpdateTodo = zod.object({
  id: zod.number(),
  status: zod.union([zod.literal(0), zod.literal(1), zod.literal(2)]),
  type: zod.union([zod.literal("todo"), zod.literal("goal")]),
  title: zod.string(),
  content: zod.string(),
});

export const cUpdateTodo: ExpressRequestHandler = async (req, res, next) => {
  try {
    const body: ParamsApiUpdateTodoItem = sUpdateTodo.parse(req.body);
    // ...
    res.success<ReturnApiUpdateTodoItem>(todo, "成功更新待办项");
  } catch (err) {
    logger.error("error in updating todo", err);
    next(err);
  }
};

列表项类型命名

• 列表项类型采用 *ListItem 的命名方式，比如：UserListItem。

Vue组件相关命名

Props命名

• 初始化属性：default + PropName
• 显示相关：show + PropName
• 功能性：PropName + able
• 禁用：disabled
• 额外内容：extra
• 图标：icon

事件命名

• 触发事件：on + EventName
• 前置事件：before + EventName
• 后置事件：after + EventName