命名约定

提示

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

常规的命名约定这里就不赘述了。比如：

• 变量和函数采用驼峰命名法（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);
  }
};