# niuheplugin

**Repository Path**: poetic/niuheplugin

## Basic Information

- **Project Name**: niuheplugin
- **Description**: niuhe 文件的 vscode 插件
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: http://niuhe.zuxing.net
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-04-18
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教程
本插件基于强大的 [`niuhe IDL`接口定义语言](http://niuhe.zuxing.net/chapter2/section3.html)，支持 `Go` 服务端、`TypeScript/Vue` 前端代码及API文档的代码生成工具。
> live.com 账号丢失, niuhe 插件后续更新移动到了这里
线上教程
- [niuhe 插件使用教程](http://niuhe.zuxing.net/) 官方教程
- 需要 `.vsix` 文件的可以加QQ群 `971024252` 联系管理员获取


# 使用本插件
- 图标点击生成: 安装后在资源管理器顶部会发现 ![entry icon](https://img.footprint.gyzuxing.com/niuhe/niuhedoc05.png) 图标, 点击即可生成代码, 同时在视图的标题菜单也会出现 ![entry icon](https://img.footprint.gyzuxing.com/niuhe/niuhedoc05.png) 图标, 点击即可。
- `niuhe idl 生成` 命令生成
    - 在 `command+shift+p` 中输入 `niuhe` 使用 `niuhe idl 生成` 命令生成;
    - 在资源管理起中在任意文件右键, 使用第一个`niuhe idl 生成`

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

# niuhe 语法
`niuhe` 文件语法上类似 `python`. 下面进行简单介绍, 具体说明请参阅教程 [niuhe 语法](http://niuhe.zuxing.net/chapter2/section3.html)

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

定义 `app` name(`admin`), 默认为 `admin`
```python
#app=admin
```

## 定义整数常量
```python
class AuthTypeEnum(ConstGroup)
    ALL = Item(0, '所有人可见')
    SOME = Item(1, '部分人可见')
    ADMIN = Item(2, desc='管理员可见')
    NONE = Item(value=3, desc='无人可见')
```
生成的代码
```go
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` 为一个结构开始标记

## 定义请求结构
```python
class UserItem():
    '''用户信息, class 注释例子, 注释可选'''
    nickname = required.String()
    avatar = optional.String(desc='头像', depr=True, ver='1.1')
```
> `desc` 为字段描述. `depr` 标记为 `deprecated`, 值为 `True`/`true`. `ver` 为版本号, `string` 格式

生成的代码
```go
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` 如:
```python
class NoneReq(Message):
    '''这是类说明, 可选'''
    pass
```
> 更多信息请查阅[字段的定义](http://niuhe.zuxing.net/chapter2/section3.html#%E5%AD%97%E6%AE%B5%E5%AE%9A%E4%B9%89)

## 定义方法
```python
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` 生成在同一文件内.

方法的定义分部分的和全部的两种
```python
  POST("获取用户信息", '/api/user/info/')
  POST("获取用户信息", '/api/user/info/', NoneReq, UserItem)
  RPC('RPC demo', url='/api/user/info/')
```
### `RPC` 方式定义请求
`RPC` 语法定义如下:
```python
RPC('desc', [url/get/post=]'/mode/view/name/')[.args(...)][.returns(...)][.codes(...)]
```
其中 `.args`, `.returns`,`codes` 都是可选的
一个例子:
```python
    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方式定义接口](http://niuhe.zuxing.net/chapter2/section3.html#rpc-%E6%96%B9%E5%BC%8F%E5%AE%9A%E4%B9%89%E6%8E%A5%E5%8F%A3)

## 数据库格式
`conf/appName.yaml` 中 db 配置格式
```yaml
db:
    main:user:pwd@tcp(host:port)/database_name?charset=utf8mb4
```

# .config.json5 配置
生成代码时自动在 `niuhe` 文件夹下生成 `.config.json5` 文件, 可根据项目需要自定义功能:
```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"`
```json5
{
  langs: ["go","docs"],
}
```
> 添加 `docs` 后会在 `niuhe` 文件夹下生成 `.docs.json5` 文档自定义文件。
>
> AI编程时可将 `swagger.json` 作为 MCP 给 AI 投喂, 提升编程质量, [点此查看接入方法](http://niuhe.zuxing.net/chapter3/section4.html)

# xorm 生成 model, dao, service, niuhe 代码
当 `niuhe` 文件夹下存在 `.model.niuhe` 文件时将会生成对应 `class` 名字的 `xorm` 代码  
```python
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` 协议和编码转换为目标语言的协议代码, 参阅 [生成其他语言协议](http://niuhe.zuxing.net/chapter4/section2.html)
- 【推荐】通过 `template` 模板生成其他语言的代码, 参阅 [用 template 生成其他语言协议](http://niuhe.zuxing.net/chapter4/section6.html)

# 更多
以上简述了本插件的基本功能以及 `niuhe` 语法, 更多功能请访问[niuhe 插件官方教程](http://niuhe.zuxing.net/) 获取更丰富支持。