2 Star 0 Fork 0

ccait-dev/fast-api

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
BSD-3-Clause

fast-api

介绍

基于gin+gorm的极简api服务,真正意义上的轻量级开发框架,内置的api/fast路由组提供了基于 restful风格的默认CRUD操作数据表。

软件架构

gin+gorm,数据库支持mysql、sqlite、postgresql、sqlserver

开发环境

Go1.23.0

安装依赖

go mod download
go mod tidy

下载指定依赖包

go get gitee.com/ccait-dev/fast-api

如版本冲突可能还需要清理模块缓存

go clean -modcache

编译二进制文件

go build

运行二进制文件

sh ./fast-api

编译并运行源代码

 go run main.go

使用Makefile

make #格式化go代码 并编译生成二进制文件
make build #编译go代码生成二进制文件
make clean #清理中间目标文件
make test #执行测试case
make check #格式化go代码
make cover #检查测试覆盖率
make run #直接运行代码
make lint #执行代码检查
make docker #构建docker镜像

配置文件 /config/application.yml

1. 开启极简 API

api:
  port: #端口
  fast: true #true为开启,或用数据源名称数组指定哪几个数据源开放fast-api 
  fastGroup: /fast-api #fast-api的路径前辍,默认为/fast-api
  serverName: FastApi #服务名称,可选参数 
  methods: GET, POST, PUT, DELETE, OPTIONS #允许的请求方式,不填默认所有
  disableSnowflakeId: false #禁用雪花ID,默认启用 
  disableMapper: false #禁用Mapper模式,默认启用

或指定允许操作的表名为白名单

api:
  fast: ["user", "logs"] #开启白名单模式

2. 定义路由

api:
  routes:
    - url: /login #绝对路径
      method: POST #请求方式
      handler: LoginHandler #通过函数处理map的key选择处理函数
      auth: #接口权限(可选)
        handler: AuthHandler #处理中间件
        permission: "sys:admin:login" #接口权限标识
    - url: /api/:db/:model/login #Mapper模式api,db为数据源,model为数据结构体,结构体字段支持validate
      method: POST
      validation: #参数校验,此处设置的优先级高于model中的validate定义
        mail: email
        account: required
    - url: /fast-api/:db/:table/create #fast-api,db为数据源,table为表名,示例:/fast-api/4s-sys/accounts/create
      validation: #fast-api也可以定义参数校验
        mail: email
        account: required

* 注意:启用Mapper模式下无需填handler,路由url规则为倒数第二节为model名称,末节为定义映射的方法名。

  • 启用Mapper模式下映射路由方法
package model

import (
	"gitee.com/ccait-dev/fast-api/fast/database/entity"
	"github.com/gin-gonic/gin"
	"gorm.io/gorm"
	"log"
)

/*
函数说明:函数名Login对应路由url的login
参数说明: @ctx 为gin的上下文
      @params 前端提交的参数
      @db 数据库操作对象
指针说明:(model Accounts),Accounts为你的Model
*/
func (model Accounts) Login(ctx *gin.Context, params map[string]interface{}, db *gorm.DB) error {
	var msg = "this is login"
	log.Println(msg)
	//这里使用gore.DB查询数据库
	//gorm.DB.Find(params)
	
	//gin.Context返回结果
	ctx.JSON(200, entity.ResponseData{Message: msg})
	return nil
}
注意: 映射路由方法最好在model目录下新增一个文件定义,比如account.go下建一个accountDao.go写Action函数,这样的做好处是数据库表设计修改时使用工具生成的Model可以直接复盖掉原有的model文件。
  • 定义字段校验示例
type User struct {
    Name    string `validate:"required"`
    Age     int    `validate:"gte=0,lte=100"`
    Email   string `validate:"email"`
    Password string `validate:"required,min=6"`
}

3. 设置数据源

api:
  datasource:
    # prometheus: 支持配置prometheus
    config: #gorm的配置,具体选项参考gorm项目文档
      prepareStmt: true
      allowGlobalUpdate: true
      disableAutomaticPing: false
    pools: #数据库连接池配置
      maxOpenConns: 20
      maxIdleConns: 10
      connMaxLifetime: 60000
      connMaxIdleTime: 600000
    connections: #数据库连接设置
      databaseName: #数据源名,一般指库名
        driver: mysql #数据库类型,支持mysql、sqlite、postgresql、sqlserver
        connectString: username:password@tcp(localhost:3306)/dbname
  routes:
    - url: /api/:db/accounts/login #Mapper模式下的context以/api/:db开头,db为数据源名称
      method: POST

启动fast-api服务

package main
import (
    "gitee.com/ccait-dev/fast-api/fast"
	. "gitee.com/ccait-dev/fast-api/fast/types"
	"gitee.com/ccait-dev/fast-api/fast/database/entity"
	"github.com/gin-gonic/gin"
	"gorm.io/gorm"
)

func main() {
	server := fast.Server{}
	server.Start(types.Options{
		Handles: types.HandleMap{ /*** Handles为可选参数,指自定义路由的处理程序映身表,application.yml配置路由时填的handler就是这里的key。 ***/
			"LoginHandler": func(ctx *gin.Context, params map[string]interface{}, db *gorm.DB) error {
				ctx.JSON(200, entity.ResponseData{Message: "this is login"})
				return nil
			},
		},
		ModelMapper: make(map[string]interface{}), /*** 启用mapper模式时,路由Url倒数第二节为Model名称时会与ModelMapper中的key匹配并映身到相应的handler,注意key为Model的小驼峰规则,Url尾节为Action,即与Model绑定的func。 ***/
		OnBeforeStart: func(eng *gin.Engine, config *config.AppConfig) {}, /*** 启动事件,服务装配完毕在启动前会调用该勾子,可在此处增加自定义gin的全局勾子函数,如路由拦截、鉴权。 ***/
	})
}

更多gin用法

参考Gin文档:https://gin-gonic.com/zh-cn/docs/

fast-api内置的CRUD 接口

接口请求规则: /fast-api/:db/:table
注: db=数据库名,table=表名

1. 新增数据

接口地址: //${服务地址:端口}/fast-api/:db/:table/create
请求方式: POST
参数格式: json、form表单
注意: 提交字段为文件类型时,该表下必须要有${field}_filename字段,${field}表示对应的字段名

2. 更新数据

接口地址: //${服务地址:端口}/fast-api/:db/:table/update
请求方式: PUT
参数格式: json、form表单
注意: 提交字段为文件类型时,该表下必须要有${field}_filename字段,${field}表示对应的字段名

3. 删除数据

接口地址: //${服务地址:端口}/fast-api/:db/:table/delete
请求方式: DELETE
参数格式: json、form表单
json示例: {id: 123456} #或 {id: [123456]}

4. 查询数据

接口地址: //${服务地址:端口}/fast-api/:db/:table/read
请求方式:  GET
参数格式: json、url参数
json参数示例: {id: 123456}
url参数示例: id=123456
分页参数示例: {
  count: false, #是否只返回总数
  export: false, #是否导出Excel
  page: {
    pageSize: 20,
    pageIndex: 1,
  },
  query: [{ #查询条件
    id: 2000
  }],
  orderBy: {
    id: 'desc'
  }, 
  select: ['field1', 'field2'], #选择字段
  data: [] #返回数据
}
注意: 分页参数格式只支持json
返回数据: {
  result: {
    data: [...], #返回查询数据
    page: { pageSize, pageIndex, totalPages },
    total: 99999,
  },
  message: 'ok',
  errorCode: 0,
}
  • 注意:多个查询条件之前默认关系为 AND,可修改配置项queryMode: OR改变,字段值匹配默认为=,更多的匹配方式可使用 EL 表达式

El表达式查询条件

字段名以$符号开头表示值须按El表达式查询解析条件,值需以${}括起,括弧内对应的字段名同样须以$符号开头表示,否则被认为字符串,可以双$符号代表当前字段

查询参数query支持El表达式,表达式写法如下所示:

  • 条件查询表达式
{
  "$name": "${$name = 字典,component=zjlj}", //条件匹配操作符可以用=、>、>=、<=、<>、!=、CONTAINS、BEGIN、END
  "$component": "${name CONTAINS 字典,component=kk}"
}

{
  "$name": "${$$ END 字典,component=kk}" //此处$$等同于$name
}
  • IN查询: ${1,2,3,4,5,...}
{
  "$id: "${1,2,3,4,5}"
}
  • 数字范围值查询: ${1-3,5-7,...}
{
  "&id: "${1-3,5-7}"
}
  • 时间范围值查询: ${2022/01/01 00:00:00 - 2022/01/01 01:00:00,...}

    注意:时间格式为 yyyy/MM/dd HH:mm:ss-yyyy/MM/dd HH:mm:ss 或 yyyy-MM-dd HH:mm:ss~yyyy-MM-dd HH:mm:ss

{
  "$create_time: "${2022/01/01 00:00:00 - 2022/01/01 01:00:00}"
}

{
  "$create_time: "${2022-01-01 00:00:00 ~ 2022-01-01 01:00:00}"
}

5. 查询联表数据

接口地址: //${服务地址:端口}/fast-api/:db/read-join
请求方式:  GET
参数格式: json、form表单
json参数示例: {id: 123456}
分页参数示例: {
  count: false, #是否只返回总数
  export: false, #是否导出Excel
  page: {
    pageSize: 20,
    pageIndex: 1,
  },
  query: [{
    id: 2000
  }],
  "joins": [{ #多表联查
    "table": "salary", #表名
    "alias": "a", #别名
    "joinMode": "inner" #联表方式
  }, {
    "table": "archives",
    "alias": "b",
    "joinMode": "Inner",
    "onList": [{
      "name": "b.id",
      "value": "a.archives_id",
      "algorithm": "EQ"
    }]
  }],
  orderBy: {
    id: 'desc'
  },
  select: ['a.field1', 'b.field2'], #选择字段
}
注意: 分页参数格式只支持json

6. 导入数据

接口地址: //${服务地址:端口}/fast-api/:db/:table/import
请求方式:  PUT
参数格式: form表单
json参数示例: {fieldName: blob}

7. 下载文件

接口地址: //${服务地址:端口}/fast-api/:db/:table/:field/download
请求方式:  GET
参数格式: json、form表单
json参数示例: {id: 123123}

GORM操作数据库

  • 复杂数据库查询需求须通过handler处理,注册的handler中会将已建好连接的gorm.DB对象带入

GORM使用参考文档:https://gorm.io/zh_CN/docs

BSD 3-Clause License Copyright (c) 2024, linlurui Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

简介

基于gin+gorm的极简api服务,真正意义上的轻量级开发框架,内置的api/fast路由组提供了基于 restful风格的默认CRUD操作数据表。 展开 收起
README
BSD-3-Clause
取消

发行版

暂无发行版

贡献者

全部

近期动态

不能加载更多了
马建仓 AI 助手
尝试更多
代码解读
代码找茬
代码优化
Go
1
https://gitee.com/ccait-dev/fast-api.git
git@gitee.com:ccait-dev/fast-api.git
ccait-dev
fast-api
fast-api
master

搜索帮助