教程

本插件基于强大的 niuhe IDL接口定义语言，支持 Go 服务端、TypeScript/Vue 前端代码及API文档的代码生成工具。

线上教程

niuhe 插件使用教程官方教程
需要 .vsix 文件的可以加QQ群 971024252 联系管理员获取

使用本插件

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

生成 go 代码时, 命令行支持 gofmt 会更好

niuhe 语法

niuhe 文件语法上类似 python. 下面进行简单介绍, 具体说明请参阅教程 niuhe 语法

入口

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

定义 app name(admin), 默认为 admin

#app=admin

定义整数常量

class AuthTypeEnum(ConstGroup)
    ALL = Item(0, '所有人可见')
    SOME = Item(1, '部分人可见')
    ADMIN = Item(2, desc='管理员可见')
    NONE = Item(value=3, desc='无人可见')

生成的代码

var AuthTypeEnum struct {
	*niuhe.IntConstGroup
	ALL  niuhe.IntConstItem `name:"所有人可见" value:"0"`
	SOME niuhe.IntConstItem `name:"部分人可见" value:"1"`
	ADMIN niuhe.IntConstItem `name:"管理员可见" value:"2"`
	NONE niuhe.IntConstItem `name:"无人可见" value:"3"`
}

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

定义请求结构

class UserItem():
    '''用户信息, class 注释例子, 注释可选'''
    nickname = required.String()
    avatar = optional.String(desc='头像', depr=True, ver='1.1')

desc 为字段描述. depr 标记为 deprecated, 值为 True/true. ver 为版本号, string 格式

生成的代码

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

class 表示定义的是一个结构, 结构变量修饰符为label.type, 以及可选的说明注释组成.

label

required, optional, repeated, mapping

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

type

Integer, Decimal, Float, Long, String, Boolean, Message, Enum,StringEnum, File, Any

Integer 生成 int
Decimal 生成 float64
Float 生成 float64
Long 生成 int64
String 生成 string
Boolean 生成 bool 请求时对应0和1
Message 对应定义的 Message 结构. 通过 cls 指定，如: users = repeated.Message(desc='用户列表', cls=UserItem)
Enum 对应定义的 ConstGroup 结构. 通过 group 指定，如: auth = repeated.Enum(desc='认证类型', group=AuthTypeEnum)
File 读取 header 中对应的文件
Any map[string]any

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

class NoneReq(Message):
    '''这是类说明, 可选'''
    pass

更多信息请查阅字段的定义

定义方法

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

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

方法

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

路由

路由由/mode/view/name/ 三段(有且只支持三段)组成, mode 相同的会生成在同一个文件夹下, mode 和 view 相同的会生成在同一文件内, 同一个 view 下的 name 生成在同一文件内.

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

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

`RPC` 方式定义请求

RPC 语法定义如下:

RPC('desc', [url/get/post=]'/mode/view/name/')[.args(...)][.returns(...)][.codes(...)]

其中 .args, .returns,codes 都是可选的一个例子:

    RPC('RPC测试用例', get='/api/xxx/yyy/').args(
        name   = required.String(desc='用户名'),
        password    = required.String(desc='密码'),
    ).returns(
        open_id = required.String(desc='用户open_id'),
        account_info = required.Message(cls=AccountInfo, desc='账户信息'),
    ).codes(
        LanguageType.ZH_CN, comm.Errors.NOT_FOUND,Item(501, '服务器错误')
    )

args 为请求参数, returns 为返回参数, codes 为错误码, langs 中添加 route 时有效会生成映射代码

RPC 方式将请求参数和返回参数定义到一起, 阅读更友好. 成员语法和定义 class 无差异, 更多信息请查阅RPC方式定义接口

数据库格式

conf/appName.yaml 中 db 配置格式

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

.config.json5 配置

生成代码时自动在 niuhe 文件夹下生成 .config.json5 文件, 可根据项目需要自定义功能:

{
  app: "", // 为生成的代码中的 app 名称, 默认为空字符串, 空字符串时同 #app=app_name
  gomod: "", // 为生成的代码中的 gomod 名称, 默认为为空字符串, 空字符串时同 app
  langs: [], // 为生成的语言类型, 默认为 "go"。支持的语言有 "go","ts","docs","route","protocol","vite" 分别为 go, typescript, swagger.json 文档, route 为生成的 go route 信息
  tstypes: [], //  langs 中支持 "ts" 时有效, 为生成的 ts 接口文件路径, 默认为 typings/api.ts 文件, 可定义多个, 如: tsapi=["full_api_path1", "full_api_path2"]
  tsapi: [], // langs 中支持 "ts" 时有效, 为生成的 ts 类型文件路径, 默认为 typings/types.d.ts 文件, 可定义多个, 如: tstypes=["full_types_path1","full_types_path2"]
  tsoptional: false, // langs 支持 "ts" 时 optional 是否添加?, 默认为 false
  showlog: false, // 为生成代码时是否生成日志, 默认为不打印日志, 打开时，日志在项目目录下 niuhe.log 中, 生成错误时可进行排查
  endcmd: [], // 为生成代码后执行的命令, 默认为空, 一般第一个为命令名, 后续为参数, 如: go mod tidy 则定义为 ["go","mod","tidy"]
}

生成 swagger json 文档

本功能默认是关闭的, 打开开关为在 .config.json5 中的 langs 中添加 "docs"

{
  langs: ["go","docs"],
}

添加 docs 后会在 niuhe 文件夹下生成 .docs.json5 文档自定义文件。

AI编程时可将 swagger.json 作为 MCP 给 AI 投喂, 提升编程质量, 点此查看接入方法

xorm 生成 model, dao, service, niuhe 代码

当 niuhe 文件夹下存在 .model.niuhe 文件时将会生成对应 class 名字的 xorm 代码

include('comm.niuhe')
#alias 可选, 默认为空, 为表名和相关定义名
#mode 可选 默认值为 api,
#niuhe 可选, 默认值为 False, 在生成对应的 niuhe 是否覆盖已存在的 niuhe 文件内容
#dao 可选, 默认值为 False, 在生成对应的 dao 是否覆盖已存在的 dao 文件内容
#service 可选, 默认值为 False, 在生成对应的 service 是否覆盖已存在的 service 文件内容
#model 可选, 默认值为 False, 在生成对应的 model 是否覆盖已存在的 model 文件内容
#vite 可选, 默认值为 False, 在生成对应的 vite 是否覆盖已存在的 vite 文件内容, 需在 .config.json5 中 langs 中添加 "vite"
#这里是做示例用, 实际开发中直接写 class Config():即可
class Config(alias='系统配置', mode='api', niuhe=True, dao=True, service=True, model=True, vite=True):
    '''系统配置表'''
    name = required.String(desc='配置名称', index=True, search=True, len=255, nontull=True)# index 加索引, len varchar 最大长度, notnull 是否为空 search 分页查询时是否出现在参数中
    value = required.Long(desc='配置值', search=True)
    state = required.Enum(desc='状态', group=comm.StateEnum)

上述定义会生成一个表最简单的增删改查 xorm 代码和对应的 niuhe api 定义。需要注意的时, 需要手动将生成的 niuhe 文件 include 进 all.niuhe 中

生成其他语言协议代码

目前支持通过两种方式生成其他语言的协议代码

可通过 protocol 协议和编码转换为目标语言的协议代码, 参阅生成其他语言协议
【推荐】通过 template 模板生成其他语言的代码, 参阅用 template 生成其他语言协议

以上简述了本插件的基本功能以及 niuhe 语法, 更多功能请访问niuhe 插件官方教程获取更丰富支持。

niuhe

dequan

教程