// 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方便直接删除目录重新生成

6.3 KiB Raw Blame History Unescape Escape

规范目录

命名

包名package

变量

常量

接口

结构体

方法

注释

数据库设计

API设计风格

Api定义尽量保持一致：(动作+资源)

请求参数结构体命名为handler后方法名+Req

返回结果结构体命名为handler后方法名+Res

6.3 KiB

Raw Blame History