From 128c7dc95bb7d21446ca83038a8de8031beaddc7 Mon Sep 17 00:00:00 2001 From: villain <284549247@qq.com> Date: Mon, 11 Dec 2023 13:30:13 +0800 Subject: [PATCH] update go and vue guide details --- README.md | 2 + go.md | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ vue.md | 41 ++++++++++++ 3 files changed, 239 insertions(+) create mode 100644 go.md create mode 100644 vue.md diff --git a/README.md b/README.md index 8220690..81638da 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,9 @@ release: 发布新版本 * [vue官方风格指南](https://cn.vuejs.org/style-guide/) * [vue-element-admin 风格指南](https://panjiachen.github.io/vue-element-admin-site/zh/guide/advanced/style-guide.html) +* [开发约定](vue.md) 主要看这个 ## 后端相关 * [实效Go编程](https://go-zh.org/doc/effective_go.html) +* [开发约定](go.md) 主要看这个 diff --git a/go.md b/go.md new file mode 100644 index 0000000..09dd654 --- /dev/null +++ b/go.md @@ -0,0 +1,196 @@ +# 规范目录 + +[命名](#命名) + +[包名package](#包名package) + +[变量](#变量) + +[常量](#常量) + +[接口](#接口) + +[结构体](#结构体) + +[方法](#方法) + +[注释](#注释) + +[数据库设计](#数据库设计) + +[API设计风格](#api设计风格) + + +## 命名 +文件和目录命名一律采用小写，不用驼峰式，尽量见名思义，看见文件名就可以知道这个文件下的大概内容。尽量和标准库不要冲突。 +其中测试文件以_test.go结尾，除测试文件外，命名不出现。 + +例子： + +stringutil.go， stringutil_test.go + +## 包名package +包名用小写,使用短命名,尽量和标准库不要冲突。 +包名统一使用单数形式。 + +## 变量 +变量命名一般采用驼峰式，当遇到特有名词（缩写或简称，如DNS）的时候，特有名词根据是否私有全部大写或小写。 + +例子： + +apiClient、URLString + +## 常量 +常量命名一般采用大写字母和下划线，如MAX_CONN_NUM。 +同变量规则，力求语义表达完整清楚，不要嫌名字长。 +如果模块复杂，为避免混淆，可按功能统一定义在package下的一个文件中。 + +## 接口 +单个函数的接口名以 er 为后缀 + +type Reader interface { + Read(p []byte) (n int, err error) +} +两个函数的接口名综合两个函数名，如: + +type WriteFlusher interface { + Write([]byte) (int, error) + Flush() error +} +三个以上函数的接口名类似于结构体名，如: + +type Car interface { + Start() + Stop() + Drive() +} + +## 结构体 +结构体名应该是名词或名词短语，如Account,Book，避免使用Manager这样的。 +如果该数据结构需要序列化，如json， 则首字母大写， 包括里面的字段。 + +## 方法 +方法名应该是动词或动词短语，采用驼峰式。将功能及必要的参数体现在名字中， 不要嫌长， 如updateById，getUserInfo. + +如果是结构体方法，那么 Receiver 的名称使用缩写，一般使用结构体名的首字母或前两个字母(小写)作为 Receiver 的名称。 如： + +func (f foo) method() { + ... +} + +func (re *Receiver) method() { + ... +} +对于结构体方法中，Receiver命名应该统一， 要么都使用值， 要么都用指针。 + +## 注释 +每个包都应该有一个包注释，位于 package 之前。如果同一个包有多个文件，只需要在一个文件中编写即可；如果你想在每个文件中的头部加上注释，需要在版权注释和 Package前面加一个空行，否则版权注释会作为Package的注释。如： + + +// Copyright 2009 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. +package net +每个以大写字母开头（即可以导出）的方法应该有注释，且以该函数名开头。如： + +// Get 会响应对应路由转发过来的 get 请求 +func (c *Controller) Get() { + ... +} +大写字母开头的方法以为着是可供调用的公共方法，如果你的方法想只在本包内掉用，请以小写字母开发。如: + +func (c *Controller) curl() { + ... +} +注释应该用一个完整的句子，注释的第一个单词应该是要注释的指示符，以便在 godoc 中容易查找。 + +注释应该以一个句点 . 结束 + + +## 数据库设计 + +* 表名统一采用单数形式，如user_info +* 字段名统一采用驼峰式，如小写加下划线，如user_id +* 数据表设计时索引名称要加上表名(或缩写，索引名称也尽量避免过长)前缀，idx/uni后缀,索引名不能重复,postgresql数据库时索引名全局唯一 +* 每个表必须要有主键，不然goctl生成的模型文件会报错 +* 每个表必须带上created_at、updated_at和deleted_at字段，方便生成仓库文件 软删除可以在仓库创建时选择是否使用 +* 数据库关键字不能用作字段名， 如：desc， asc 等 pg select 带关键字字段时会报错 + + +## API设计风格 +以go-zero框架开发为例: + +* `接口请求参数和返回结果统一下划线分隔`, 请求参数结构体以Req结尾 返回结果结构体以Res结尾 +* 代码目录和文件名称全部小写 `不加下划线` (模型和repository生成文件除外) +* app下创建应用api文件统一放在apifile目录 以main.api为主文件 +* 数据库表名全部改成单数(方便生成工具使用) +* 接口查询和更新Req参数结构非必传(optional)字段用指针，为统一方便记忆全部请求参数都使用指针类型, + 这样logic获取请求参数都是指针 (因为指针结构体请求时不传该参会为nil类型，使copier复制时就会跳过修改此字段) eg： + +``` + UpdateAppInstanceReq { + AppKey *string `path:"appKey"` + UserId *int64 `json:"userId,optional"` + Name *string `json:"name,optional"` + Logo *string `json:"logo,optional"` + } +``` + +* GET请求参数使用参数的flag要写成form传递 用json传递会导致参数无法获取到 + +``` +QueryDeviceReq { + Page *uint64 `form:"page,optional,default=1"` + PageSize *uint64 `form:"page_size,optional,default=20"` + GroupId *int64 `form:"group_id,optional"` + IotProductKey *string `form:"iot_product_key,optional"` + Keyword *string `form:"keyword,optional"` + } +``` + +* Api创建和删除非必要不在logic return 内容, 200响应即成功,eg: + +``` + @handler Create + post / (CreateReq) + @handler Delete + delete /:id (IdPathReq) +``` +* ##### Api定义尽量保持一致：(动作+资源) +* 查询 => QueryXXX +* 创建 => CreateXXX +* 编辑 => UpdateXXX +* 删除 => DeleteXXX +* 详情 => DetailXXX +其他: +* 上传 => UploadXXX +* 触发 => TriggerXXX +* ##### 请求参数结构体命名为handler后方法名+Req +* ##### 返回结果结构体命名为handler后方法名+Res + +``` +示例: +service smartenergy { + @doc "查询触发器" + @handler QueryTrigger + get / (QueryTriggerReq) returns (QueryTriggerRes) + + @doc "创建触发器" + @handler CreateTrigger + post / (CreateTriggerReq) returns (TriggerRes) + + @doc "编辑触发器" + @handler UpdateTrigger + put /:id (UpdateTriggerReq) + + @doc "触发器详情" + @handler DetailTrigger + get /:id (TriggerIdReq) + + @doc "删除触发器" + @handler DeleteTrigger + delete /:id (TriggerIdReq) +} +``` + +* 尽量避免修改handler 因为修改api文件重新生成不会生成已有handler 无修改过handler方便直接删除目录重新生成 diff --git a/vue.md b/vue.md new file mode 100644 index 0000000..df744e2 --- /dev/null +++ b/vue.md @@ -0,0 +1,41 @@ +# vue约定规范 + +* ##### 代码风格配置： +``` +* 使用element 框架时，eslint配置使用："eslint-plugin-vue",默认element-admin框架已完成配置 +大部分规则也都配置在了eslint-plugin-vue之中，当没有遵循规则的时候会报错 +* 单独安装: npm install eslint-plugin-vue -D +* 使用quasar框架时创建(npm quasar create)时已完成配置 +* 提交npm lint检查代码通过后再提交代码, 也可以添加husky检查，但过于强制可以熟悉后再使用 +``` + +* ##### vue3 统一使用setup风格,更简洁易明 +``` + +