196 lines
6.3 KiB
Markdown
196 lines
6.3 KiB
Markdown
# 规范目录
|
||
|
||
[命名](#命名)
|
||
|
||
[包名package](#包名package)
|
||
|
||
[变量](#变量)
|
||
|
||
[常量](#常量)
|
||
|
||
[接口](#接口)
|
||
|
||
[结构体](#结构体)
|
||
|
||
[方法](#方法)
|
||
|
||
[注释](#注释)
|
||
|
||
[数据库设计](#数据库设计)
|
||
|
||
[API设计风格](#api设计风格)
|
||
|
||
|
||
## 命名
|
||
文件和目录命名一律采用小写，不用驼峰式，尽量见名思义，看见文件名就可以知道这个文件下的大概内容。尽量和标准库不要冲突。
|
||
其中测试文件以_test.go结尾，除测试文件外，命名`不出现下划线`。
|
||
|
||
例子：
|
||
|
||
stringutil.go， stringutil_test.go
|
||
|
||
## 包名package
|
||
包名用全小写,使用短命名,尽量和标准库不要冲突。
|
||
包名统一使用单数形式。
|
||
|
||
## 变量
|
||
变量命名一般采用驼峰式，当遇到特有名词（缩写或简称，如DNS）的时候，特有名词根据是否私有全部大写或小写, `不使用下划线`。
|
||
|
||
例子：
|
||
|
||
apiClient、URLString
|
||
|
||
## 常量
|
||
同变量规则，力求语义表达完整清楚，不要嫌名字长。
|
||
如果模块复杂，为避免混淆，可按功能统一定义在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方便直接删除目录重新生成
|