插件介绍

Vscode niuhe 插件是一款面向 golang 的后端 IDL 定义翻译插件, 支持 go 程序的路由, 出入参定义；同时支持将 idl 翻译为 typescript 定义

插件使用

下面从一个空项目 adminsvr 开始讲解 niuhe 插件的基本使用。使用前需要先安装 niuhe 插件；插件介绍页有详细教程

程序入口

程序默认将项目下的 niuhe/all.niuhe 文件作为入口，在开始前需要读取项目名及配置参数，然后是对应的配置参数读取。

开始前在项目下创建 niuhe 目录和niuhe/all.niuhe 文件。并在其中定义项目名app。此时将项目名定义为adminsvr。 插件语法高亮请选择为 python

定义请求参数和 API

接下来演示一个简单的 Hello world 例子, 继续编辑我们的 all.niuhe 文件如下:

python 复制代码

#app=adminsvr

class SysTestReq(Message):
    '''测试请求参数'''
    say = required.StringField(desc='这是一个必填 string 类型请求参数')

class SysTestResp(Message):
    '''测试返回参数'''
    answer = required.StringField(desc='作为返回参数时, 必填字段可忽略, 这里是定义类型的')

with services():
    GET('演示例子', '/api/sys/test/', SysTestReq, SysTestResp)

下面对上面的代码进行逐行解读:

第1行定义了项目名为 adminsvr
第3行定义了一个名为 SysTestReq 的结构, 其语法为 class 开头,(Message): 结尾
第4行用为结构 SysTestReq 添加注释, 注释语法同 python
第5行为结构定义了一个名为 say 的 string 的必填参数
第7-9行同3-5行
第11行用 with services(): 作为开始标记, 以下是定义 api 开始
第12行定义了一个路径为/api/sys/test 的 GET api, 其请求结构为 SysTestReq, 返回结构为 SysTestResp.

代码生成

可通过点击(1)资源管理器顶部和(2)工具栏中的 </>图标生成代码，也支持在(3)资源管理器中选中任意文件并右键中 niuhe idl 生成, (4) Command + Shift + P 快捷键中输入 niuhe 查找 niuhe idl 生成 共4种方式触发代码生成。

方式1和3	方式2	方式4

使用以上方式中的任意一种生成项目基础代码后文件结构如下:

shell 复制代码

.
├── README.md ---- 说明文档
├── conf
│   └── adminsvr.yaml ---- 配置文件
├── makefile  ---- mac/linux 中的 make 定义文件
├── niuhe
│   └── all.niuhe ---- 项目入口
├── niuhe.log --- 生成 log, 如果生成出错, 可根据 log 定义位置
└── src
    └── adminsvr
        ├── app
        │   ├── api --- model 文件夹
        │   │   ├── protos
        │   │   │   └── gen_protos.go --- 自动生成文件
        │   │   └── views --- views 文件夹
        │   │       ├── gen_sys_views.go
        │   │       ├── init.go
        │   │       └── sys_views.go --- 具体入口
        │   └── common
        │       └── consts
        │           └── gen_consts.go -- 常量定义
        ├── config
        │   └── config.go --- conf/*yaml 定义读取文件
        ├── main.go  --- main 入口
        └── xorm --- xorm 定义文件夹, 结构为 model - dao - service
            ├── daos
            │   └── init.go
            ├── models
            │   └── models.go
            └── services
                └── init.go

运行程序

README.md 文件中包含了运行项目的基础说明, 我们先复制 mod 部分代码让程序运行起来 cd src/adminsvr && go mod init adminsvr && go mod tidy && go mod vendor && cd ../../ && make run。顺利的话可见项目运行起来，此时在浏览器中输入 http://localhost:9999/api/sys/test/?say=hellow 得到如下内容:

json 复制代码

{"message":"Not Implemented","result":-1}

实现 Hello world

src/adminsvr/app/api/views/sys_views.go 文件代码如下

go 复制代码

package views

// Generated by niuhe.idl

import (
	"adminsvr/app/api/protos"

	"github.com/ma-guo/niuhe"
)

type Sys struct {
	_Gen_Sys
}

// 演示例子
func (v *Sys) Test_GET(c *niuhe.Context, req *protos.SysTestReq, rsp *protos.SysTestResp) error {
	return niuhe.NewCommError(-1, "Not Implemented")
}
func init() {
	GetModule().Register(&Sys{})
}

第18行即为我们访问得到的结果, 接下来我们修改方法实现实现 hello world, 修改后 16-19行代码为