Vscode niuhe 插件使用教程(2) - 官方教程解释

官方教程已经上线, 请访问: niuhe.zuxing.net/

使用本插件

• 图标点击生成. 安装后在资源管理器顶部会发现</>图标, 点击即可生成代码, 同时在视图的标题菜单也会出现 </>图标, 点击即可。
• niuhe idl 生成 命令生成, 1 在 command+shift+p 中输入 niuhe 使用 niuhe idl 生成 命令生成;2. 在资源管理器中在任意文件右键, 使用第一个niuhe idl 生成

niuhe  语法

niuhe 文件语法上遵从 python 语法(语法高亮请选择 python). 可通过 include 引入文件，include 文件之前需要处于同一文件夹下。如

include('comm.niuhe')

class UserInfo(Message):
    base = optional.MessageField(desc='基本信息', cls=comm.UserBaseInfo)

注意

生成 golang 代码时, 命令行支持 gofmt 会更好(生成代码后会调用 gofmt 命令格式化文件内容)

入口

默认读取当前工作区下的 niuhe 文件夹 内的 all.niuhe 文件. 可通过修改设置来更改此入文件的位置。

定义 app name(项目名), 默认为 admin

#app=admin

同时可定义 gomod 变量(可选) gomod 为 go.mod 中的 module, 默认值为 app。定义语法为

#gomod=admin

gomod 是解决项目名过长或包含非字母/数字字符时在部分语言中生成语法错误时使用的别名, 定义 gomod 时, 部分情况下将覆盖项目名

定义整数常量

class AuthTypeEnum(ConstGroup)
    ALL = Item(0, '所有人可见')
    SOME = Item(1, '部分人可见')

生成的代码

var AuthTypeEnum struct {
	*niuhe.IntConstGroup
	ALL  niuhe.IntConstItem `name:"所有人可见" value:"0"` // value: 0, name: 所有人可见
	SOME niuhe.IntConstItem `name:"部分人可见" value:"1"` // value: 1, name: 部分人可见
}

此代码位于 src/{gomod}/app/common/consts/gen_consts.go 文件中

其中 ConstGroup 为常量类型, AuthTypeEnum 为本组枚举的名字. class 为一个结构开始标记

定义字符串常量

class GenderEnum(ConstGroup):
    '''用户性别定义'''
    MAN = Item('男', '男士')
    WOMAN = Item('女', '女士')

生成的代码

var GenderEnum struct {
	*niuhe.StringConstGroup
	MAN   niuhe.StringConstItem `name:"男士" value:"男"` // value: 男, name: 男士
	WOMAN niuhe.StringConstItem `name:"女士" value:"女"` // value: 女, name: 女士
}

此代码位于 src/{gomod}/app/common/consts/gen_consts.go 文件中

其中 ConstGroup 为常量类型, GenderEnum 为本组枚举的名字. class 为一个结构开始标记

字符串常量定义和整数常量定义仅仅在 value 上有区别, 其他语法无异。需要注意的是同一个ConstGroup定义中不能同时包含整数常量和字符串常量

定义请求结构

class UserItem(Message):
    '''用户信息, class 注释例子, 注释可选'''
    nickname = required.StringField()
    avatar = optional.StringField(desc='头像')

生成的代码

type UserItem struct {
	Nickname string `json:"nickname" zpf_name:"nickname" zpf_reqd:"true"` //
	Avatar   string `json:"avatar" zpf_name:"avatar"`     // 头像
}

Message 表示定义的是一个结构。

结构变量修饰符为重复类型.类型, 以及可选的说明注释组成

重复类型

required, optional, repeated, mapping

• required 表示这个此结构作为请求参数时本参数必填
• optional 表示此结构作为请求结构时本参数可选
• repeated 表示生成的成员为数组
• mapping 表示生成的成员为 map 形式, 内部可填充任意值

成员类型

IntegerField, DecimalField, FloatField, LongField, StringField, BooleanField, MessageField, EnumField,StringEnumField, FileField, AnyField

• IntegerField 生成 int
• DecimalField 生成 float64
• FloatField 生成 float64
• LongField 生成 int64
• StringField 生成 string
• BooleanField 生成 bool 请求时对应0和1
• MessageField 对应定义的 Message 结构. 通过 cls 指定，如: users = repeated.MessageField(desc='用户列表', cls=UserItem)
• EnumField 对应定义的 ConstGroup 结构. 通过 group 指定，如: auth = repeated.EnumField(desc='认证类型', group=AuthTypeEnum)
• FileField 读取 header 中对应的文件
• AnyField map[string]interface{}

定义一个无成员的空结构时使用pass 如:

class NoneReq(Message):
    pass

定义方法

with services():
    POST("获取用户信息", '/api/user/info/', NoneReq, UserItem)
	...

with services(): 为定义请求路由的开始结构为: 方法·(注释,路由,请求参数结构,wraps(返回数据结构)) 组成。

方法

请求方法当定义了 POST, GET, PUT, PATCH, DELETE, HEAD 和 OPTIONS 七种

路由

路由由/model/view/方法/ 三段组成, model 相同的会生成在同一个文件夹下, model 和 view 相同的会生成在同一文件内, 同一个 view 下的方法会生成在同一文件内.

方法的定义分部分的和全部的两种

    POST("获取用户信息", '/api/user/info/')
    POST("获取用户信息", '/api/user/info/', NoneReq, UserItem)

方法参数成员仅支持基础类型以及基础类型数组(required,optional,repeated), 基础类型包括IntegerField, DecimalField, FloatField, LongField, StringField, BooleanField, EnumField,StringEnumField。即不包括 repeated.MessageField 成员结构的解析

数据库格式

conf/appName.yaml 中 db 配置格式

db:
    main:user:pwd@tcp(host:port)/database_name?charset=utf8mb4

进阶 - 更多自定义信息

在 niuhe 文件夹下新建文件 .config, 注:

• .config 为本地定义文件, 不需要跟随 git 版本提交
• 配置项不能添加注释

支持生成 typescript

#langs=ts
#tstypes=full_types_file_path1, full_types_file_path2,...
#tsapi=full_api_file_path1,full_api_file_path2,...
#tsoptional
#showlog

完整示例

配置项	配置说明	示例
#langs	支持的语言, 目前支持 go,ts, docs, route, 默认支持 go	#langs=ts
#tstypes	自定义 types.d.ts 全路径，不支持相对路径。 格式为用英文逗号, 分隔的数组, 可生成到多个位置	#tstypes=~/hrhelper/typings/lib.props.d.ts
#tsapi	自定义 api.ts 全路径, 不支持相对路径。格式为用英文逗号, 分隔的数组, 可生成到多个位置	#tsapi=~/hrhelper/src/utils/api.ts
#tsoptional	optional 修饰的字段添加 ?, 默认不添加	#tsoptional
#showlog	是否显示 niuhe.log 文件, 默认不生成, niuhe.log 文件用于打印生成代码过程中打印的辅助信息，当出现意外生成失败时打开本开关，用于辅助排查问题	#showlog

ts 代码生成主要是协同开发使用, 如ABC三人同时开发一个项目, A负责后端, B，C负责开发前端, 而B和C两人的前端项目位于不同位置, 因此在生成前端代码时需要灵活地指定生成的前端代码位置

route 会生成 src/{app}/protos/gen_router.go 所有路由信息列表文件。生成定义的路由信息结构如下。本文件在每次生成时会被覆盖, 请不要手动编辑。

type RouteItem struct {
	Method string `json:"method"` // API 请求方法
	Path   string `json:"path"`   // API 请求路径
	Name   string `json:"name"`   // API 名称
}