本项目是一个服务模板, 你可以使用它来快速的搭建一个服务。
日常工作中,大家都会维护接口文档? 开发接口服务吧? 你会碰到已下的场景么?
- 你希望接口文档在git仓库里面管理么, 这样你可以看到接口文档的历史版本
- 你希望通过接口文档直接生成接口代码么, 包括序列化对象那些
- 你希望你的接口文档可以跟着服务走么, 直接通过服务暴露的端口在浏览器查看么
- 你希望定义的接口可以同时被内部通过rpc调用, 也可以被外部通过http+json调用么
- 你希望定义的流式接口可以同时被内部通过rpc调用, 也可以被外部通过http-chunked+json调用么
- 你希望定义的接口可以直接被websocket调用么
- 你希望你的接口可以暴露出一些默认指标给Prometheus监控么
- 你希望你的服务可以自带Profile接口, 可以通过Go Profile工具来分析你的服务么
- 你希望你的服务自带Gops, 可以通过Gops工具来分析你的服务么
- 你希望你的服务可以自带退出信号的捕获和优雅退出么
- 你希望你的服务可以自带日志的配置文件么, 可以配置日志级别、输出的文件、格式、文件回
- 你希望你的服务支持交叉编译, 生成不同平台和架构的二进制文件么
- 你希望使用配置文件管理程序的一些行为么
- 你需要多阶段构建, 把你的服务打包成一个合理体积的 docker image么
如果你需要上面的任何一个功能, 你可以了解下这个项目。
使用了 grep-gateway
protoc-gen-doc
grpcurl
gops
protoc
工具不了解的可以看下如何使用
- 在
demo
目录中定义你的接口, 例如demo.proto
- 使用
demo/gen.sh
生成接口代码 - 在
internal/impl
目录中实现你的接口, 例如impl.go
- 在
conf/services.yaml
中配置服务暴露的端口以及日志信息
本项目采用grpc protobuf作为接口定义语言,使用grpc-gateway作为grpc和http的转换桥梁。
所以你需要熟悉grpc接口定义语言, 如果你不熟悉, 你可以化个30分钟的时间看看官方的文档
接口定义语言定义好之后, 你需要使用protoc工具生成api代码和api文档(html 当然也有其他的格式)
如果你想生成其他格式的接口文档, 请参阅 protoc-gen-doc
可以使用浏览器查看接口文档。
http://localhost:8070/api/docs
本项目使用yaml作为配置文件的格式, 你可以在 conf/services.yaml
中配置服务的端口, 日志的配置文件路径等
当然你可以扩展其他的配置信息, 比如业务逻辑上的一些开关, 你可以修改 internal/config/config.go
中的 Config
结构体
本项目使用logrus作为日志框架, 你可以在 conf/services.yaml
中配置日志的输出级别, 输出文件, 输出格式, 文件回滚配置等
如果你想配置额外的信息,比如把日志输出到syslogd等,可以参考logrus的文档
服务启动之后,会监听系统的退出信号,当接收到退出信号之后,会等当前的请求处理完毕之后,再退出服务。
当然这需要你的业务逻辑支持超时退出,你需要在处理函数中加入
CurrentReqCount.Inc()
defer func() {
CurrentReqCount.Dec()
}()
自动集成了prometheus暴露基础指标, 可以使用下面的地址查看
支持gops来debug服务
提供了默认的 build.sh
支持不同系操作系统和不同架构的编译
这里提供了一些通过命令行调用服务的工具, 只用这些工具就可以测试你的服务.
同时你也很容易的使用一些性能测试工具, 比如apache ab, ghz等
当然你也可以直接使用ide调用你的服务, 这里提供了一个 Goland
的示例。
所有的测试工具都在 testing
目录下有相关的参考。
curl -X POST -d '{"age":18,"name":"scguo"}' http://127.0.0.1:8090/demo
curl -X POST -d '{"name":"scguo","age":1}{"name":"scguo","age":18}' -H "Transfer-Encoding: chunked" 127.0.0.1:8090/stream
支持使用sse协议, 通过制定Accept方式为text/event-stream来调用服务
curl -X POST -d '{"name":"scguo","age":1}' -H "Accept:text/event-stream" 127.0.0.1:8090/halfstream -vvv
grpcurl -plaintext -d '{"age":18,"name":"scguo"}' 127.0.0.1:8080 example.DemoService/OneWay
grpcurl -plaintext -d @ 127.0.0.1:8080 example.DemoService.Stream < grpc_stream.dat
websocat "ws://127.0.0.1:8091/stream?method=POST" -H='Origin: ws://127.0.0.1:8091/stream?method=POST' -v
- 使用日志context把一次请求的所有日志都打印到一起