Skip to content

Commit

Permalink
添加文档和操作指导
Browse files Browse the repository at this point in the history
  • Loading branch information
yangyile committed Oct 12, 2024
1 parent 94d0a3f commit 52fd539
Show file tree
Hide file tree
Showing 7 changed files with 227 additions and 26 deletions.
119 changes: 103 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,28 +3,115 @@ Vue 3 frontends and Kratos backends integration toolkit. Enabling seamless commu

做后端做久了偶尔也要做做前端。

在学前端时发现vue3用起来还行,就想着用vue3做前端连接kratos的后端服务,因此做了个中间的胶水工具,让两个语言能够更顺畅的对接
在学前端时发现vue3用起来还行,就想着用vue3做前端连接kratos的后端服务。

## 把kratos的proto接口定义转换为 typescript 语言的 grpc 的请求
这里只能给 makefile 的参考内容,因为开发者的工具路径不同,三方包的路径和版本不同
因此做了个中间的胶水工具,让两个语言能够更顺畅的对接。

## 把kratos的proto接口定义转换为 typescript 语言的 grpc 的 client 客户端代码
### 使用的工具链安装
主要是这里:
[需要使用的 protoc-gen-ts 工具网页](https://www.npmjs.com/package/protoc-gen-ts)
很明显的,里面有 usage 的指导:
```
npm install -g protoc-gen-ts
```

### 工具链安装的操作
```
#需要看看是否已安装:
admin@lele-de-MacBook-Pro ~ % which protoc-gen-ts
protoc-gen-ts not found
#假如没有安装就安装:
admin@lele-de-MacBook-Pro ~ % npm install -g protoc-gen-ts
added 1 package in 4s
1 package is looking for funding
run `npm fund` for details
#安装完毕以后看位置:
admin@lele-de-MacBook-Pro ~ % which protoc-gen-ts
/Users/admin/.nvm/versions/node/v18.17.0/bin/protoc-gen-ts
#安装的位置非常重要。
```

### 使用工具生成代码
#### 根据 proto 得到 typescript grpc 的 client 客户端代码
注意:这里只能给 makefile 的参考内容,因为开发者的工具路径不同,三方包的路径和版本不同

#### 配置样例1:
这是我的某个环境的逻辑,需要你在 kratos 项目的 Makefile 里面增加这段:
``` makefile
web_api_grpc_ts:
mkdir -p ./bin/web_api_grpc_ts.out
protoc \
--plugin=protoc-gen-ts=/Users/admin/.nvm/versions/node/v18.17.0/bin/protoc-gen-ts \
--ts_out=./bin/web_api_grpc_ts.out \
--proto_path=./api \
--proto_path=./third_party \
$(API_PROTO_FILES)

protoc \
--plugin=protoc-gen-ts=/Users/admin/.nvm/versions/node/v18.17.0/bin/protoc-gen-ts \
--ts_out=./bin/web_api_grpc_ts.out \
--proto_path=./third_party \
$(THIRD_PARTY_GOOGLE_API_PROTO_FILES)
```
你需要在`Makefile`找路径的逻辑里增加(这还只是mac/ubuntu系统的,windows系统的你自己也写写吧):
``` makefile
THIRD_PARTY_GOOGLE_API_PROTO_FILES=$(shell find third_party/google/api -name *.proto)
```

#### 配置样例2:
这是我的其它环境的逻辑,需要你在 kratos 项目的 Makefile 里面增加这段:
``` makefile
web_api_grpc_ts:
mkdir -p ./bin/web_api_grpc_ts.out
protoc \
--plugin=protoc-gen-ts=/home/yangyile/.nvm/versions/node/v20.14.0/bin/protoc-gen-ts \
--ts_out=./bin/web_api_grpc_ts.out \
--proto_path=./api \
--proto_path=./proto3ps \
$(API_PROTO_FILES)

protoc \
--plugin=protoc-gen-ts=/home/yangyile/.nvm/versions/node/v20.14.0/bin/protoc-gen-ts \
--ts_out=./bin/web_api_grpc_ts.out \
--proto_path=./proto3ps \
$(THIRD_PARTY_GOOGLE_API_PROTO_FILES)
mkdir -p ./bin/web_api_grpc_ts.out
protoc \
--plugin=protoc-gen-ts=/home/yangyile/.nvm/versions/node/v20.14.0/bin/protoc-gen-ts \
--ts_out=./bin/web_api_grpc_ts.out \
--proto_path=./api \
--proto_path=./proto3ps \
$(API_PROTO_FILES)
protoc \
--plugin=protoc-gen-ts=/home/yangyile/.nvm/versions/node/v20.14.0/bin/protoc-gen-ts \
--ts_out=./bin/web_api_grpc_ts.out \
--proto_path=./proto3ps \
$(THIRD_PARTY_GOOGLE_API_PROTO_FILES)
```
你需要在`Makefile`找路径的逻辑里增加(这还只是mac/ubuntu系统的,windows系统的你自己也写写吧):
``` makefile
THIRD_PARTY_GOOGLE_API_PROTO_FILES=$(shell find proto3ps/google/api -name *.proto)
```

具体使用时请自己根据实际编写吧,确保工具链相同。

#### 通过工具得到代码
```
make web_api_grpc_ts
```
假如不报错的话就会得到你想要的结果代码
```
admin@lele-de-MacBook-Pro helloworld % make web_api_grpc_ts
admin@lele-de-MacBook-Pro helloworld %
admin@lele-de-MacBook-Pro helloworld % cd bin/web_api_grpc_ts.out
admin@lele-de-MacBook-Pro web_api_grpc_ts.out % ls
google helloworld
admin@lele-de-MacBook-Pro web_api_grpc_ts.out %
```
但是很明显的,这个代码是基于grpc协议的,假如你需要把代码改为底层使用http协议传输,也有多种解决方案。

比如使用 web-grpc 代理等,但是需要额外的配置。

其中我认为最简单的,就是把客户端底层代码改改,让调用grpc的变为调用http接口,在底层使用`axios`请求。

这样的好处是,以函数调用的形式请求http接口,而且参数和返回值都是 typescript 带类型的,就非常的方便。

因此接下来就是使用这个工具把代码再改改。

## 把grpc请求逻辑替换为使用http请求逻辑
### 安装
```
Expand Down
4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ require (
github.com/yyle88/erero v1.0.11
github.com/yyle88/osexistpath v0.0.5
github.com/yyle88/runpath v1.0.9
github.com/yyle88/zaplog v0.0.11
github.com/yyle88/zaplog v0.0.12
go.uber.org/zap v1.27.0
)

Expand All @@ -19,7 +19,7 @@ require (
github.com/pkg/errors v0.9.1 // indirect
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
github.com/spf13/pflag v1.0.5 // indirect
github.com/yyle88/mutexmap v1.0.5 // indirect
github.com/yyle88/mutexmap v1.0.6 // indirect
github.com/yyle88/sure v0.0.23 // indirect
github.com/yyle88/syntaxgo v0.0.30 // indirect
go.uber.org/multierr v1.11.0 // indirect
Expand Down
8 changes: 4 additions & 4 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ github.com/yyle88/formatgo v1.0.11 h1:bJuHyTAV/L3RD2BfGuk85APwu15qCA8rey+TnnhUgt
github.com/yyle88/formatgo v1.0.11/go.mod h1:/ghTCbopOb7VT//Wr10jLHLNIwhznaFXqynT24muBOk=
github.com/yyle88/must v0.0.3 h1:mtQeanevihE0p4Imkx0XkXU6cQZiKxANDXu0PMJElkw=
github.com/yyle88/must v0.0.3/go.mod h1:BGo8wMJL1cXHkVRvGKveRx1V0dkZaJBe9ETxV9Lpfh8=
github.com/yyle88/mutexmap v1.0.5 h1:sJS5NRY5NbFgVTUGuL4wMZv5dgq1oiDBbGm7f/AdZu4=
github.com/yyle88/mutexmap v1.0.5/go.mod h1:lAEDkpXe9iSU0/8L/SaXAQ6TUa+4A9nnl9OQ56zHEQY=
github.com/yyle88/mutexmap v1.0.6 h1:wIkEZmENn/+kgVt4uYNElMXUzyKKE784DSfVwnAUwaw=
github.com/yyle88/mutexmap v1.0.6/go.mod h1:lAEDkpXe9iSU0/8L/SaXAQ6TUa+4A9nnl9OQ56zHEQY=
github.com/yyle88/osexistpath v0.0.5 h1:wp/+SsfPoUr54aSvp4oNa34vD0PXRFqTd6eTgkkWMTE=
github.com/yyle88/osexistpath v0.0.5/go.mod h1:xMNzLQG/UWp3DOKg+A3lJdyrDDjzMLquTmUvVn+RWfU=
github.com/yyle88/runpath v1.0.9 h1:J8K8qqg2ecXuTwhNllvwiwQtNePWZswXpk1RI8mlI1Q=
Expand All @@ -38,8 +38,8 @@ github.com/yyle88/sure v0.0.23 h1:PjVSQ9yFzYwvXtMtr5tV07ojbp7pqh6RloiYGCgLNkE=
github.com/yyle88/sure v0.0.23/go.mod h1:sY79ts753i1JSH7AOvwITLpWwDnQ7u8w8kvz4ZJIYHo=
github.com/yyle88/syntaxgo v0.0.30 h1:USU0AckbdAxvdSWuZ9gZ5quGHY+rsWza8XLrSU0a3pI=
github.com/yyle88/syntaxgo v0.0.30/go.mod h1:V0La63ghvOANWpeOJjWpABndGkIS2rUMr066WBYopBQ=
github.com/yyle88/zaplog v0.0.11 h1:g7IfF03vfJCgJrlr3qMeCbeRi3nxneA3n5W8lYSjZes=
github.com/yyle88/zaplog v0.0.11/go.mod h1:RbgWRlved+hKCcpFd7UV4MTq9NdrqIIYumngKExIxkk=
github.com/yyle88/zaplog v0.0.12 h1:3MHmBHobGTPL7EjWxaatEG0fX3NPF+kHCYzgTlzWIXE=
github.com/yyle88/zaplog v0.0.12/go.mod h1:AlCwptNgHCLrKVgCzp64FDqPQn/xZux3yGVIYjxqr2A=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
Expand Down
1 change: 1 addition & 0 deletions internal/demos/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
helloworld
100 changes: 100 additions & 0 deletions internal/demos/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
GOHOSTOS:=$(shell go env GOHOSTOS)
GOPATH:=$(shell go env GOPATH)
VERSION=$(shell git describe --tags --always)

ifeq ($(GOHOSTOS), windows)
#the `find.exe` is different from `find` in bash/shell.
#to see https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/find.
#changed to use git-bash.exe to run find cli or other cli friendly, caused of every developer has a Git.
#Git_Bash= $(subst cmd\,bin\bash.exe,$(dir $(shell where git)))
Git_Bash=$(subst \,/,$(subst cmd\,bin\bash.exe,$(dir $(shell where git))))
INTERNAL_PROTO_FILES=$(shell $(Git_Bash) -c "find internal -name *.proto")
API_PROTO_FILES=$(shell $(Git_Bash) -c "find api -name *.proto")
else
INTERNAL_PROTO_FILES=$(shell find internal -name *.proto)
API_PROTO_FILES=$(shell find api -name *.proto)
#想把第三方的这些也收集下来,再使用命令生成第三方包(因为自动生成好像不是很好使)
THIRD_PARTY_GOOGLE_API_PROTO_FILES=$(shell find third_party/google/api -name *.proto)
endif

.PHONY: init
# init env
init:
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install github.com/go-kratos/kratos/cmd/kratos/v2@latest
go install github.com/go-kratos/kratos/cmd/protoc-gen-go-http/v2@latest
go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest
go install github.com/google/wire/cmd/wire@latest

.PHONY: config
# generate internal proto
config:
protoc --proto_path=./internal \
--proto_path=./third_party \
--go_out=paths=source_relative:./internal \
$(INTERNAL_PROTO_FILES)

.PHONY: api
# generate api proto
api:
protoc --proto_path=./api \
--proto_path=./third_party \
--go_out=paths=source_relative:./api \
--go-http_out=paths=source_relative:./api \
--go-grpc_out=paths=source_relative:./api \
--openapi_out=fq_schema_naming=true,default_response=false:. \
$(API_PROTO_FILES)

.PHONY: build
# build
build:
mkdir -p bin/ && go build -ldflags "-X main.Version=$(VERSION)" -o ./bin/ ./...

.PHONY: generate
# generate
generate:
go generate ./...
go mod tidy

.PHONY: all
# generate all
all:
make api;
make config;
make generate;


web_api_grpc_ts:
mkdir -p ./bin/web_api_grpc_ts.out
protoc \
--plugin=protoc-gen-ts=/Users/admin/.nvm/versions/node/v18.17.0/bin/protoc-gen-ts \
--ts_out=./bin/web_api_grpc_ts.out \
--proto_path=./api \
--proto_path=./third_party \
$(API_PROTO_FILES)

protoc \
--plugin=protoc-gen-ts=/Users/admin/.nvm/versions/node/v18.17.0/bin/protoc-gen-ts \
--ts_out=./bin/web_api_grpc_ts.out \
--proto_path=./third_party \
$(THIRD_PARTY_GOOGLE_API_PROTO_FILES)

# show help
help:
@echo ''
@echo 'Usage:'
@echo ' make [target]'
@echo ''
@echo 'Targets:'
@awk '/^[a-zA-Z\-\_0-9]+:/ { \
helpMessage = match(lastLine, /^# (.*)/); \
if (helpMessage) { \
helpCommand = substr($$1, 0, index($$1, ":")); \
helpMessage = substr(lastLine, RSTART + 2, RLENGTH); \
printf "\033[36m%-22s\033[0m %s\n", helpCommand,helpMessage; \
} \
} \
{ lastLine = $$0 }' $(MAKEFILE_LIST)

.DEFAULT_GOAL := help
13 changes: 13 additions & 0 deletions internal/demos/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
在这里使用 kratos 的 helloworld 项目,就可以体验工具。

https://go-kratos.dev/docs/getting-started/start/

根据官方网站的指导,在当前目录里,创建 helloworld 项目。

使用 make all 和 make build 把它跑起来。

接着修改其Makefile的内容。

我在这里放了个Makefile,使用它,替换 helloworld 里面的。

就可以使用这个文件里的子命令得到 typescript 的客户端代码。
8 changes: 4 additions & 4 deletions vue3npm/src/rpcviahttp/rpcviahttp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,8 @@ function rewritePathParam<T extends object>(uriPath: string, input: T): string {

if (value === undefined) {
// 尝试将蛇形命名法转换为小驼峰命名法
const camelcaseParamName = name2camelcase(paramName)
value = input[camelcaseParamName]
const pnm: string = paramName2camelcase(paramName)
value = input[pnm]
}

if (value === undefined) {
Expand All @@ -93,6 +93,6 @@ export function urxCombine(urb: string, uri: string): string {
return urx
}

function name2camelcase(str: string): string {
return str.replace(/_([a-z])/g, (g) => g[1].toUpperCase())
function paramName2camelcase(paramName: string): string {
return paramName.replace(/_([a-z])/g, (g) => g[1].toUpperCase())
}

0 comments on commit 52fd539

Please sign in to comment.