docs: add doc for command cwgo-doc (cloudwego#955)

Co-authored-by: chaoranz758 <[email protected]>
chaoranz758 · Feb 29, 2024 · 7213e1f · 7213e1f
1 parent 6126084
commit 7213e1f
Show file tree

Hide file tree

Showing 13 changed files with 1,136 additions and 0 deletions.
diff --git a/content/en/docs/cwgo/tutorials/doc/_index.md b/content/en/docs/cwgo/tutorials/doc/_index.md
@@ -0,0 +1,10 @@
+---
+title: "Doc"
+linkTitle: "Doc"
+weight: 6
+description: >
+---
+
+cwgo supports generating model code and basic CURD code for document database through IDL(thrift/protobuf) structures, and currently supports Mongodb.
+
+The underlying use of Mongodb curd generation tool is [Mongodb](https://github.com/mongodb/mongo-go-driver), the supported functions and usage rules are detailed in [usage_rule](/docs/cwgo/tutorials/doc/usage_rule/).
diff --git a/content/en/docs/cwgo/tutorials/doc/commands.md b/content/en/docs/cwgo/tutorials/doc/commands.md
@@ -0,0 +1,60 @@
+---
+title: "commands"
+linkTitle: "commands"
+weight: 1
+description: >
+---
+
+## Basic Commands
+
+Use `cwgo doc -h` to view usage details:
+
+```sh
+NAME:
+   cwgo doc - generate doc model
+
+              Examples:
+                # Generate doc model code
+                cwgo doc --name mongodb --idl {{path/to/IDL_file.thrift}}
+
+
+USAGE:
+   cwgo doc [command options] [arguments...]
+
+OPTIONS:
+   --idl value [ --idl value ]                                                  Specify the IDL file path. (.thrift or .proto)
+   --module value, --mod value                                                  Specify the Go module name to generate go.mod.
+   --out_dir value                                                              Specify output directory, default is current dir.
+   --model_dir value                                                            Specify model output directory, default is biz/doc/model.
+   --dao_dir value                                                              Specify dao output directory, default is biz/doc/dao.
+   --name value                                                                 Specify specific doc name, default is mongodb.
+   --proto_search_path value, -I value [ --proto_search_path value, -I value ]  Add an IDL search path for includes.
+   --thriftgo value, -t value [ --thriftgo value, -t value ]                    Specify arguments for the thriftgo. ({flag}={value})
+   --protoc value, -p value [ --protoc value, -p value ]                        Specify arguments for the protoc. ({flag}={value})
+   --verbose                                                                    Turn on verbose mode, default is false. (default: false)
+   --help, -h                                                                   show help (default: false)
+```
+
+## Specification
+
+- idl                       Specify the main IDL path required for code generation
+
+- module/-mod                Specify the go mod name, which must be specified outside of GOPATH. In GOPATH, the default name is the path relative to GOPATH
+
+- out_dir                   Specify the code output directory, which defaults to the command execution directory
+
+- model_dir                 Specify the model code directory generated by thriftgo or protoc, which defaults to biz/doc/model
+
+- dao_dir                   Specify the directory for the generated doc curd code, which defaults to biz/doc/dao
+
+- name                      Specify the document type database name for generating code, default to mongodb, currently only mongodb is supported
+
+- proto_search_path/-I    Specify the IDL search directory to use when IDL type is proto
+
+- thriftgo/-t             Parameters passed through to thriftgo
+
+- protoc/-p               Parameters passed through to protoc
+
+- verbose                   Default to false, specified as true will output more detailed log content
+
+- help/-h                 help command
diff --git a/content/en/docs/cwgo/tutorials/doc/example_pb.md b/content/en/docs/cwgo/tutorials/doc/example_pb.md
@@ -0,0 +1,110 @@
+---
+title: "protobuf usage"
+linkTitle: "protobuf usage"
+weight: 5
+description: >
+---
+
+## Simple Example
+
+### Create video.proto
+
+```protobuf
+syntax = "proto3";
+
+package video;
+
+option go_package = "idl/video";
+
+// mongo.InsertVideo = |InsertVideo(ctx context.Context, video *video.Video) (interface{}, error)|
+message Video {
+  int64 Id = 1; // go.tag=|bson:"id,omitempty"|
+  bytes Data = 2; // go.tag=|bson:"data,omitempty"|
+}
+```
+
+### Execute Command
+
+```sh
+cwgo doc -idl video.proto --proto_search_path . --module {your module name}
+```
+
+### Generate Code
+
+The directory structure for generating code refers to [layout](/docs/cwgo/tutorials/doc/layout/).
+
+## Detailed Example
+
+### Create user.proto and video.proto
+
+**user.proto**
+
+```protobuf
+syntax = "proto3";
+
+package user;
+
+import "idl/video.proto";
+
+option go_package = "idl/user";
+
+/*
+mongo.InsertOne = |InsertOne(ctx context.Context, user *user.User) (interface{}, error)|
+mongo.InsertMany = |InsertMany(ctx context.Context, user []*user.User) ([]interface{}, error)|
+mongo.FindUsernameOrderbyIdSkipLimitAll = |FindUsernames(ctx context.Context, skip, limit int64) ([]*user.User, error)|
+mongo.FindByLbLbUsernameEqualOrUsernameEqualRbAndAgeGreaterThanRb = |FindByUsernameAge(ctx context.Context, name1, name2 string, age int32) (*user.User, error)|
+mongo.UpdateContactByIdEqual = |UpdateContact(ctx context.Context, contact *user.UserContact, id int64) (bool, error)|
+mongo.DeleteByYdEqual = |DeleteById(ctx context.Context, yd []user.YDType) (int, error)|
+mongo.CountByAgeBetween = |CountByAge(ctx context.Context, age1, age2 int32) (int, error)|
+mongo.BulkInsertOneUpdateManyByIdEqual = |BulkOp(ctx context.Context, userInsert *user.User, userUpdate *user.User, id int64) (*mongo.BulkWriteResult, error)|
+mongo.TransactionBulkLbInsertOneUpdateManyByIdEqualRbCollectionVideoCollectionInsertManyVideos =
+|TransactionOp(ctx context.Context, client *mongo.Client, videoCollection *mongo.Collection, userInsert *user.User, userUpdate *user.User, id int64, videos []*video.Video) error|
+ */
+message User {
+  int64 Id = 1; // go.tag=|bson:"id,omitempty"|
+  string username = 2; // go.tag=|bson:"username"|
+  int32 Age = 3; // go.tag=|bson:"age"|
+  string City = 4; // go.tag=|bson:"city"|
+  bool Banned = 5; // go.tag=|bson:"banned"|
+  UserContact Contact = 6; // go.tag=|bson:"contact"|
+  video.Video Videos = 7; // go.tag=|bson:"videos"|
+  repeated YDType yd = 8; // go.tag=|bson:"yd"|
+}
+
+message UserContact {
+  string Phone = 1; // go.tag=|bson:"phone"|
+  string Email = 2; // go.tag=|bson:"email"|
+}
+
+enum YDType {
+  INVALID = 0;
+  DOWN = -1;
+  UP = 1;
+}
+```
+
+**video.proto**
+
+```protobuf
+syntax = "proto3";
+
+package video;
+
+option go_package = "idl/video";
+
+// mongo.InsertVideo = |InsertVideo(ctx context.Context, video *video.Video) (interface{}, error)|
+message Video {
+  int64 Id = 1; // go.tag=|bson:"id,omitempty"|
+  bytes Data = 2; // go.tag=|bson:"data,omitempty"|
+}
+```
+
+### Execute Command
+
+```sh
+cwgo doc -idl user.proto --proto_search_path . --module {your module name}
+```
+
+### Generate Code
+
+The directory structure for generating code refers to [layout](/docs/cwgo/tutorials/doc/layout/).
diff --git a/content/en/docs/cwgo/tutorials/doc/example_thrift.md b/content/en/docs/cwgo/tutorials/doc/example_thrift.md
@@ -0,0 +1,103 @@
+---
+title: "thrift usage"
+linkTitle: "thrift usage"
+weight: 4
+description: >
+---
+
+## Simple Example
+
+### Create video.thrift 
+
+```thrift
+namespace go video
+
+struct Video {
+    1: i64 Id (go.tag="bson:\"id,omitempty\"")
+    2: binary Data (go.tag="bson:\"data,omitempty\"")
+}
+(
+mongo.InsertVideo = "InsertVideo(ctx context.Context, video *video.Video) (interface{}, error)"
+)
+```
+
+### Execute Command
+
+```sh
+cwgo doc --idl video.thrift --module {your module name}
+```
+
+### Generate Code
+
+The directory structure for generating code refers to [layout](/docs/cwgo/tutorials/doc/layout/).
+
+## Detailed Example
+
+### Create user.thrift And video.thrift
+
+**user.thrift**
+
+```thrift
+namespace go user
+
+include "video.thrift"
+
+struct User {
+    1: i64 Id (go.tag="bson:\"id,omitempty\"")
+    2: string Username (go.tag="bson:\"username\"")
+    3: i32 Age (go.tag="bson:\"age\"")
+    4: string City (go.tag="bson:\"city\"")
+    5: bool Banned (go.tag="bson:\"banned\"")
+    6: UserContact Contact (go.tag="bson:\"contact\"")
+    7: list<YDType> Yd (go.tag="bson:\"yd\"");
+}
+(
+mongo.InsertOne = "InsertOne(ctx context.Context, user *user.User) (interface{}, error)"
+mongo.InsertMany = "InsertMany(ctx context.Context, user []*user.User) ([]interface{}, error)"
+mongo.FindUsernameOrderbyIdSkipLimitAll = "FindUsernames(ctx context.Context, skip, limit int64) ([]*user.User, error)"
+mongo.FindByLbLbUsernameEqualOrUsernameEqualRbAndAgeGreaterThanRb = "FindByUsernameAge(ctx context.Context, name1, name2 string, age int32) (*user.User, error)"
+mongo.UpdateContactByIdEqual = "UpdateContact(ctx context.Context, contact *user.UserContact, id int64) (bool, error)"
+mongo.DeleteByYdEqual = "DeleteById(ctx context.Context, yd []user.YDType) (int, error)"
+mongo.CountByAgeBetween = "CountByAge(ctx context.Context, age1, age2 int32) (int, error)"
+mongo.BulkInsertOneUpdateManyByIdEqual = "BulkOp(ctx context.Context, userInsert *user.User, userUpdate *user.User, id int64) (*mongo.BulkWriteResult, error)"
+mongo.TransactionBulkLbInsertOneUpdateManyByIdEqualRbCollectionVideoCollectionInsertManyVideos =
+"TransactionOp(ctx context.Context, client *mongo.Client, videoCollection *mongo.Collection, userInsert *user.User, userUpdate *user.User, id int64, videos []*video.Video) error"
+)
+
+struct UserContact {
+    1: string Phone (go.tag="bson:\"phone\"")
+    2: string Email (go.tag="bson:\"email\"")
+}
+
+enum YDType {
+  INVALID = 0;
+  DOWN = -1;
+  UP = 1;
+}
+```
+
+**video.thrift**
+
+```thrift
+namespace go video
+
+struct Video {
+    1: i64 Id (go.tag="bson:\"id,omitempty\"")
+    2: binary Data (go.tag="bson:\"data,omitempty\"")
+}
+(
+mongo.InsertVideo = "InsertVideo(ctx context.Context, video *video.Video) (interface{}, error)"
+)
+```
+
+### Execute Command
+
+```sh
+cwgo doc --idl user.thrift --module {your module name}
+```
+
+### Generate Code
+
+The directory structure for generating code refers to [layout](/docs/cwgo/tutorials/doc/layout/).
+
+
diff --git a/content/en/docs/cwgo/tutorials/doc/layout.md b/content/en/docs/cwgo/tutorials/doc/layout.md
@@ -0,0 +1,26 @@
+---
+title: "layout"
+linkTitle: "layout"
+weight: 3
+description: >
+---
+
+![image](/img/docs/cwgo_doc_generate_file.png)
+
+> biz/doc/dao/{struct name}：Store the mongodb curd code, and the generated location can be modified through --dao dir
+>
+> - {struct name}_repo.go Function interface file
+> - {struct name}_repo_mongo.go Interface implementation and specific curd code
+>
+> biz/doc/model：The code generated by thriftgo or protoc, where the go struct corresponding to the Mongodb set is located, can be modified by using --model_dir
+
+The user needs to pass in the set `*mongo.Collection` parameter and call the `New{struct name}Repository` function in `{struct name}_repo_mongo.go` to use the tool generated CURD function.
+
+Example Code:
+
+```go
+// call NewUserRepository
+userMongo := user.NewUserRepository(collection)
+// call InsertUser to insert user document to mongodb
+user.InsertUser(ctx, user)...
+```