yufeiGT / vue3_template

一套基于 Vue3 及 TypeScript 的项目开发模板，集成一些 @~crazy 功能包

Vue 3 项目开发模板

• 一套基于 Vue3 的项目模板
• NodeJS 14.18.1
• 支持 Sass
• 集成 TypeScript
• 集成 Ant Design Vue
• 集成 @~crazy 工具包
• 集成 @kotron 工具包

使用方法

• npm i 安装依赖模块
• npm run serve 运行开发模式
• npm run build 打包项目

---

前端规范

• 制定人：黄华林
• 制定日期：2024 年 1 月 6 日
• 修改日期：2024 年 1 月 6 日
• 联系邮箱：[e-mail]

node-sass 对应 NodeJS 版本

NodeJS	Supported node-sass version	Node Module
Node 20	9.0+	115
Node 19	8.0+	111
Node 18	8.0+	108
Node 17	7.0+, < 8.0	102
Node 16	6.0+	93
Node 15	5.0+, < 7.0	88
Node 14	4.14+, < 9.0	83
Node 13	4.13+, < 5.0	79
Node 12	4.12+, < 8.0	72
Node 11	4.10+, < 5.0	67
Node 10	4.9+, < 6.0	64
Node 8	4.5.3+, < 5.0	57
Node < 8	< 5.0	< 57

---

项目开发 src 目录架构

文件名称	子文件名称	使用方式	描述
api	-	import * as API from '@/api';	请求的 API 函数文件
	lib	-	API 资源包
	index.ts	-	API 入口
	launcher.ts	-	@~crazy/launcher 实例
assets	-	-	资源文件夹
	icons	-	SVG 图标
	images	-	图片资源
	stylesheets	-	全局样式表
components	-	-	Vue 组件
	Charts	-	echarts 图表组件
	Icon.vue	-	SVG 图标组件
directives	-	-	Vue 指令文件
	Loading	v-loading="xxx" 或 v-loading.body="xxx"	加载中
	ScrollToTop	v-scroll-to-top="callback"	滚动到顶部
	index.ts	-	指令入口
entity	-	import * as Entity from '@/entity'	实体
	lib	-	实体资源包
	index.ts	-	实体入口
enum	-	import * as Enum from '@/enum'	枚举
	lib	-	枚举资源包
	index.ts	-	枚举入口
store	-	-	Vuex 仓库
	modules	-	store 模块
	index.ts	-	store 入口
utils	-	import * as Utils from '@/utils';	工具函数文件
views	-	-	路由视图文件
App.vue	-	-	Vue 入口文件
main.ts	-	-	程序入口文件
router.ts	-	-	路由配置文件

---

引用规范

• 各项不同的引用空出一行隔开
• API、Entity、Enum、Utils 必须以 import * as API from '@/api' 方式引用，不能以 import { Auth } from '@/api' 方式引用
• 组件必须用 Vue 作为后缀方便识别，如 import TestVue from './test.vue'

引用顺序

// 外部包
import { ref, computed } from 'vue';
import * as KotronGlobal from '@kotron/global';

// @ 的 interface、enum、type 等
import * as Entity from '@/entity';

// @ 的工具类，API等
import * as Utils from '@/utils';
import * as API from '@/api';

// @ 的组件
import HeaderVue from '@/components/header.vue';

// 内部功能模块
import { useQuery } from './use';

// 内部组件
import TestVue from 'test.vue';

---

注释规范

• 由于 typescript 不支持单行注释的解释，因此要求所有的输出（Entity、Enum、API、函数等）使用多行注释，禁止单行注释

// 统一使用此多行注释规范
/**
 * xxxx
 * @description xxxx
 * @param xxxx
 * @returns xxxx
 */
// 不允许此多行注释
/** xxxx */

范例

// userAuth.ts
export interface UserInfo {
    /**
     * 用户 ID
     */
    id: string | number;
    /**
     * 用户名
     */
    username: string;
    /**
     * 用户昵称
     */
    nickName: string;
    // 不符合本规范的注释
    /** 图片 */
    picture: string;
}

• 其他代码内部可使用单行注释

function Login(username: string, password: string) {
    // 执行登录
    return launcher.get('/login', {
        username,
        password,
    }).then(res => {
        // 成功
    }).catch(err => {
        // 失败
    });
}

---

Entity 规范

• 输出名称

除 global.ts 文件外，所有实体必须以文件名加大驼峰在 index.ts 输出

// userAuth.ts
export * as UserAuth from './lib/userAuth.ts';

• 实体每个属性都应编写注释

• 需包含 getDefault 函数

使用 namespace 方式导出 getDefault 函数

// userAuth.ts
export interface UserInfo {
    /**
     * 用户 ID
     */
    id: string | number;
    /**
     * 用户名
     */
    username: string;
    /**
     * 用户昵称
     */
    nickName: string;
    /**
     * 图片
     */
    picture: string;
}
export namespace UserInfo {
	/**
	 * 获取默认值
	 * @returns
	 */
    export function getDefault() {
        return {
            id: null,
            username: '',
            nickName: '',
            picture: ''
        }
    }
}

---

Enum 规范

• 输出名称

除 global.ts 文件外，所有枚举必须以文件名加大驼峰在 index.ts 输出

// userAuth.ts
export * as UserAuth from './lib/userAuth.ts';

• 包含 enum 和 type 的定义

• 使用 namespace 方式导出 getDescription 函数

// userAuth.ts
export type UserType = 'A' | 'B' | 'C';
export namespace UserType {
	/**
	 * 获取描述
	 * @param value
	 * @returns
	 */
    export function getDescription(value: UserType) {
        switch(value) {
            case 'A':
                return '用户类型A';
            case 'B':
                return '用户类型B';
            case 'C':
                return '用户类型C';
			default:
				return '枚举错误';
        }
    }
}

---

API 规范

• 输出名称

所有 api 必须以文件名加大驼峰在 index.ts 输出

// userAuth.ts
export * as UserAuth from './lib/userAuth.ts';

• api 名称使用大驼峰命名方式

export function GetUserInfo() {
    // ...
}

• 定义 api 时，必须设定请求失败默认值

export function Login(){
    return launcher.get<Entity.Auth.UserInfo, undefined>('xxxx', {}, {
        // 设定默认值
		defaultResponse: Entity.Auth.UserInfo.getDefault(),
    });
}

• 带参数的请求，如需要添加请求参数的 interface，需要在返回实体的 namespace 内定义 RequestParams，不允许在别处定义

// api/lib/auth.ts
export function Login(params: Entity.Auth.UserInfo.RequestParams) {
    return launcher.post<
		Entity.Auth.UserInfo,
		Entity.Auth.UserInfo.RequestParams
	>('xxxx', params, {
		defaultResponse: Entity.Auth.UserInfo.getDefault(),
	});
}

// entity/lib/auth.ts
export interface UserInfo {
    // ....
}
export namespace UserInfo {
    /**
	 * 请求参数
	 */
	export interface RequestParams {
        // ...
    }
}

---

路由视图（.Vue）规范

为规范代码及提高代码封装思维，这里使用 Use 模式进行视图与逻辑代码分离，以功能块进行逻辑封装。提高代码可读性，使逻辑代码更加清晰简洁

文件名	描述
index.vue	视图入口
use.ts	可复用的逻辑代码
use.xxxx.ts	按功能区分的可复用逻辑代码

---