zero-api

zero-api

INSTALL

go install github.com/cuishu/zero-api@latest

使用方法

Step 1

创建golang项目

mkdir project && cd project
go mod init github.com/cuishu/api

Step 2

生成 api 模板文件

zero-api -api

zero-api 会根据 go.mod 里定义的 package 生成 .api 文件

Step 3

生成项目模板 .api文件修改完成后，执行

zero-api -f 你的 .api 文件

Step 4

编写业务逻辑

业务逻辑在logic, 是需要关注的部分

注意：

包含// Code generated by zero-api. DO NOT EDIT.的文件是不可修改的文件，再次生成的时候zero-api会覆盖文件的内容

保留字

保留字不能作为变量名称使用，区分大小写

API 说明

编写业务代码前，需要先编写API文件，整个项目是围绕 .api 文件构建的。

注释

良好的注释是必需的，注释会出现在zero-api和zero-client生成的代码和文档里

zero-api支持 C 风格注释

单行注释:

// 我是单行注释

多行注释

/*
    第一行注释
    第二行注释
*/

Tips 注释必须写在被注释的内容上方，如果存在多个注释，zero-api只会保留最后一个注释，如需多行注释，请使用多行注释语法 例:

// 第一行注释会被忽略
// 第二行也会被忽略
// 学生信息结构体 （此行注释会被保留）
type Student {

}

/**
* 教师信息结构体
* 使用多行注释
* 注释会被完整保留
*/
type Teacher {

}

API文档

.api文件的第一行必须是注释，被称为API文档。需要详细描述API功能。

一般来说，API文档应使用多行注释

info

info 部分记录了API作者、邮箱和API版本号

语法如下所示:

info (
	author: cuishu
	email: required@mail.com
	version: v1.0.0
)

author 作者

email 作者邮箱

version 版本号

版本号规则： 使用三位数版本号，如v1.0.0

变更规则(不强制要求)

第一位是主版本号
第二位是次版本号
第三位是修订次数

api 语法

数据类型

// 学生信息结构体
type Student {
    // 学生姓名
    Name string `json:"name"`
}

数据类型的定义和 go struct 定义类似，只是缺少了 struct 关键字, 是因为只打算支持这一种数据类型，没有扩充的打算

Service

Service 同样需要良好的注释

语法

/**
* Service 注释用来描述Service的功能，这部分可以简略说明
*/
service ZeroApi {
	// 每个api的注释
	@handler Add
	POST /book (AddReq) return (AddResp)

    // 每个api的注释
	@handler Delete
	DELETE /book (AddReq) return (AddResp)
}

一个Service 语句块由 service关键字、service名称和花括号组成

内部包含具体的API定义, 可存在多个定义

第一行必须是注释

装饰器 @handler是装饰器，用来声明路由的 handler 名称（@handler <函数名>），zero-api会在 logic生成一个与 handler 声明同名的文件，文件里包含一个空函数，开发者需在该函数内实现相关业务逻辑

路由 语法为: <Method> <URI> (<输入参数>) return (<返回值>)

Method 只可以使用 GET、POST、PUT、DELETE 和其对应的小写形式

URI 不做过多介绍

输入参数和返回值必须在 api 文件内定义