hitzhangjie / gorpc-cli Goto Github PK

0. parse protobuf, to find out all service defined, use this to find out all pb.Register${Service}Service TODO
1. parse project code, build AST finished
2. use regexp to found matched pb.RegisterXXXService finished
3. check the interface method defined in service XXX, expand rpc method statements finished
4. expand the method statements in rpc method recursively finished
5. support rendering in console mode, plantuml mode finished

ok, what code structure should be visualized?

1. communication btw objects, packages finished
2. control flow .... important but not urgent, I'll finish this in near future.

提炼出可复用的代码作为单独的repo，包括但不限于：

• util/fs, done
• util/compress, done
• util/log, done
• util/style

等等吧

I am trying on this, it's a little complex, not that so complex. And I am not using plantuml activity.
Displaying the participants, branches, actions all in sequential diagram maybe better to understand.

ballerina sample 1:

ballerina sample 2:

The picture above is from Ballerina microservice framework. I do some trying for golang.

Before showing some samples, I want to share my thinkings.

1. which language construct or activities should we visualize?
   I think OOP is good.
   Maybe what we care most is the Participants and Communication.
   Besides, we care the condition branches. like when something happens? If it happens, what we should do?

2. what communication stands for?

   • method call (method has receiver type): object sends message to another object
   • package exported function call: this maybe not a message passing, but it still looks important for us.
   • RPC or network activity.
   • etc.

   ps: After I do some trying on this, I think it would be better if we could specify which activity we should focus on.

3. how should we visualize these constructs or activites?

   • plantuml: plantuml is an option, but maybe we should look for better solutions.
     plantuml generates an static picture, sometime it is enough, maybe most time, it's not.
     when we reading code or trying to understand code, what we focus changes as we navigate, a little like the IDE supports code folding feature.
     some syntax like if-else/switch-case/for-loop rendered by plantuml is a little hard to understand, the alt-else/loop is not clear enough.

some samples:

1. IfStmt

func TestIfElse() {

	num := 1
	if num == 1 {
		fmt.Println("1")
	} else if num == 2 {
		fmt.Println("2")
	} else {
		fmt.Println("others")
	}
}

and relevant puml:

@startuml
participant ifstmt
alt ../../testdata/ast/ifelse.go:8:5
	ifstmt->ifstmt
	note right: stmt ../../testdata/ast/ifelse.go:9:3
else ../../testdata/ast/ifelse.go:10:9
	alt ../../testdata/ast/ifelse.go:10:12
		ifstmt->ifstmt
		note right: stmt ../../testdata/ast/ifelse.go:11:3
	else ../../testdata/ast/ifelse.go:12:9
		ifstmt->ifstmt
		note right: stmt ../../testdata/ast/ifelse.go:13:3
	end
end
@enduml

rendered picture:

ForStmt

package ast

import "fmt"

func TestForStmt() {
	for i := 0; i < 10; i++ {
		fmt.Println("hello world")
	}
}

relevant puml:

@startuml
participant forStmt
group ForStmt
	forStmt->forStmt
	note right: init ../../testdata/ast/for.go:6:6
	loop ../../testdata/ast/for.go:6:14
		forStmt->forStmt
		note right: body stmt: ../../testdata/ast/for.go:7:3
		forStmt->forStmt
		note right: post ../../testdata/ast/for.go:6:22
	end
end
@enduml

rendered picture:

take a real project as example:

Just a little try, It even cannot satisfy my own usage.

If we could find a better reprentation manner, it would be better.
I learned that the microservice framework Ballerina supports graphical editor, https://medium.com/ballerina-techblog/ballerina-vscode-plugin-graphical-editor-for-ballerina-b6af226178d6.

Maybe we could use this render method like Ballerina, though it would be much more complex. Or we could add some options to exclude/include the language constructs.

该设计最初是为了用来对存量协议提供适当的支持，目前提供了两种方式：

• 通过//@alias=的方式来修改service中的rpcname
• 通过扩展method option的方式来修改service中的rpcname

建议使用第二种，本身也是google protocol buffer推荐的方式，注释的方式难以维护，难以扩展，也不是官方推荐的方式，特别是两种方式混用的时候，非常丑陋。

以前安装是通过make install进行安装的，会通过go build -ldflags "-X pkg.var=${revision}"的形式将当前代码版本写入到二进制程序里。

现在go get方式，无法干预链接过程，需要在提交代码前，将代码中的版本变量config.GoRPCCliVersion更新为正确的版本。可以考虑通过makefile target来解决。

generate instruction like:

this file is generated by bindata, don't edit it.

更好的开发测试支持：

1.自动编译程序（带-gcflags参数），生成调试符号、禁用内联优化，方便后面调试；
2.goast分析服务接口实现（包括请求、响应类型分析）；
3.goast分析函数中外部依赖，如db、rpc调用，可以是任意函数调用；

• step1：通过配置文件的方式给出一些要分析的规则列表，如常见的分析db、rpc调用；
  db、redis等操作参数类型相对简单，rpc调用pb结合proto反射很容易可以搞定；
• step2：支持任意函数调用；
  参数类型不确定，需要遍历工程goast分析函数出入参类型，不难可能有点繁琐；
  4.启动进程，启动debugger server，并将上述接口函数入口点、db、redis、rpc调用等全部添加breakpoints；
  5.弹出界面，显示服务接口列表，用户选择并填写req、rsp，点击发送请求；
  在一次测试中，req作为测试输入，rsp用来做测试最后的断言；
  6.服务受到请求之后，开始执行对应的接口方法
  接口方法代码执行时，执行路径上的所有像db、redis、rpc调用（或用户指定函数调用），弹出界面询问输入、输出；
  • 通过debugger server api发起stepin操作，进入函数第一条指令
  • 通过FDE计算，找到函数退出地址，修改rip直接退出函数（代替真正的执行）
  • 根据用户输入，更新返回值，如更新rsp、err
    7.继续往下执行，类似mock测试中涉及到外部依赖需要mock的地方都按照步骤6中的方式来处理
    8.一条测试执行结束，整个过程中用户输入的内容：
  • 自动作为测试用例沉淀到用例配置文件中；
  • 自动生成mock函数、mock代码，不需要每位开发手动编写；
  • 自动生成测试函数，加载该配置文件，可以持续跑测试；

有两个明显的好处：

• 开发阶段，开发测试更方便了：
  • 一个用例需要mock哪些代码，可能需要多次阅读代码，这次mock掉了db，还漏了rpc，不用关心了，用到哪个mock哪个；
  • 工具自动化生成mock的代码，也不用关心mock怎么写了，每次写类似代码，太繁琐太耗时；
• 代码质量，开发真正的关心其测试覆盖率，省掉写接口测试代码、mock逻辑的耗时；

tdd模式，鼓励先规划测试用例，再投入开发，红绿红绿……
该issue提及的方式，与tdd也不冲突，只需要一个加载配置文件的helper函数辅助一下即可。

删除一下代码：

• 注释代码
• 针对非go语言的硬编码的逻辑（后续通过插件来实现），先全部删除；

以gorpc create代码生成为例，过程中涉及到了：

• 命令行参数的解析； done，不需要每次PreRunE、RunE之前显示cmd.ParseFlags(...), cobra框架里面已经做了
• pb文件的解析； done，依然通过jhump/protoreflect
• 工作目录的准备； todo，这个要看下--output有没有什么不安全的地方
• 代码生成； todo，代码模板再进一步简化下
• protoc生成； done，这个没什么要更新的
• 依赖的pb文件的protoc生成； todo，由于语言相关，依赖对应的插件，这里要通过插件形式来实现
• 各个语言后置的一些特殊逻辑；
  • 各个扩展项如validate、swagger的一些代码生成逻辑`
  • 后续如何扩展？ done, using --plugins=validator+swagger instead of --swagger --validator

按照最初我的设计：

• 这个工具是语言无关的，各个语言相关的特殊逻辑，应该通过各自的模板来解决
  实际情况是，部分同学对pb细节、gotemplate掌握的不深入，只知道在代码里面堆砌代码来解决，代码中侵入了各个语言特有的逻辑；
• 这个工具应该支持一些灵活的脚本，如自定义的mv、copy支持，允许代码生成后执行一些简单的处理，避免侵入工具代码中
  这部分，对应的同学一直拖，拖到现在也没有实现，sad
• 后续如何扩展插件，原先的设计中确实考虑不太周到，需要提供一个更好的方式来支持扩展，如针对swagger.proto的处理，能否不通过侵入代码的形式来支持到，肯定是可以的。

use --plugins instead of --mock, --swagger,

so we can keep this tool relatively stable, also we can extend it with plugins.
and we can use it like gorpc create --plugins=mock+swagger+anything.

参考以下文章实现：
https://phrase.com/blog/posts/internationalisation-in-go-with-go-i18n/

After *.proto updated, including adding service, rpc definition, we should re-generate the template project.

But we shouldn't overwritten the written code by developers.

Solutions:

1. generate some insertion points, expand the insertion points with appended code like new service, rpc definition.
2. directly read the previous code to build an AST, and parse, to determine which methods are needed to appended to the AST. Then we can rewrite the code based on new AST.

Actually, both methods need parse previous code to build an AST and parse.