proxima-book第三章

docs/course/proxima-book/第三张-单词服务/3.1.前置准备.md

@@ -0,0 +1,82 @@
+搞定了第一个微服务，第二个单词微服务，开发起来自然轻车熟路。
+
+## 代码初始化
+---
+执行以下命令，建立名为`word`的服务，同样保存在`app`目录下。
+
+```bash
+$ gf init app/word -a
+initializing...
+initialization done! 
+you can now run "cd app/word && gf run main.go" to start your journey, enjoy!
+```
+
+如法炮制，删除下列文件，留下一个空白的环境。
+```text
+app/word/api/*
+app/word/internal/controller/*
+app/word/internal/cmd/cmd.go
+```
+
+进入微服务仓库，开始正式开发。
+```bash
+$ cd app/word
+```
+
+## 生成数据模型
+---
+### 建立数据表
+在`word`数据库下，执行`SQL`语句，建立保存用户数据的表：
+```sql
+CREATE TABLE words (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+    uid INT UNSIGNED NOT NULL,
+    word VARCHAR ( 255 ) NOT NULL,
+    definition TEXT,
+    example_sentence TEXT,
+    chinese_translation VARCHAR ( 255 ),
+    pronunciation VARCHAR ( 255 ),
+    created_at DATETIME,
+    updated_at DATETIME
+);
+```
+
+### 生成dao模型
+*app/user/hack/config.yaml*
+```yaml
+gfcli:  
+  gen:  
+    dao:  
+      - link: "mysql:root:12345678@tcp(srv.com:3306)/word"  
+        descriptionTag: true
+```
+
+```bash
+$ gf gen dao
+generated: D:\project\proxima\app\word\internal\dao\words.go
+generated: D:\project\proxima\app\word\internal\dao\internal\words.go
+generated: D:\project\proxima\app\word\internal\model\do\words.go
+generated: D:\project\proxima\app\word\internal\model\entity\words.go
+done!
+```
+
+> 注意，应该在微服务仓库下执行`gf gen dao`命令，也就是`app/user`目录下，后续的其他相关操作开发也类似。
+
+### 生成pbentity模型
+*app/user/hack/config.yaml*
+```bash
+gfcli:
+  gen:  
+    dao:  
+      - link: "mysql:root:12345678@tcp(srv.com:3306)/word"  
+        descriptionTag: true  
+
+    pbentity:  
+      - link: "mysql:root:12345678@tcp(srv.com:3306)/word"
+```
+
+```bash
+$ gf gen pbentity
+generated: D:\project\proxima\app\word\manifest\protobuf\pbentity\words.proto
+done!
+```

docs/course/proxima-book/第三张-单词服务/3.2.业务逻辑.md

@@ -0,0 +1,31 @@
+和前文一样，这里简单做个样子
+
+*app/word/internal/logic/words/words.go*
+```go
+package words  
+
+import (  
+    "context"  
+
+    "github.com/gogf/gf/v2/os/gtime"
+    "proxima/app/word/internal/model/entity"
+)  
+
+func Create(ctx context.Context) (id uint, err error) {  
+    return 1, nil  
+}  
+
+func Get(ctx context.Context) (word *entity.Words, err error) {  
+    return &entity.Words{  
+       Id:                 1,  
+       Uid:                1,  
+       Word:               "hello",  
+       Definition:         "used as a greeting when you meet somebody.",  
+       ExampleSentence:    "Hello, I am oldme!",  
+       ChineseTranslation: "你好",  
+       Pronunciation:      "həˈləʊ",  
+       CreatedAt:          gtime.New("2024-12-05 22:00:00"),  
+       UpdatedAt:          gtime.New("2024-12-05 22:00:00"),  
+    }, nil  
+}
+```

docs/course/proxima-book/第三张-单词服务/3.3.协议文件.md

@@ -0,0 +1,37 @@
+这里我就从简了，只写一个`Create`和`Get`用作示例。
+
+*app/word/manifest/protobuf/words/v1/words.proto*
+```proto
+// protoc --go_out=plugins=grpc:. *.proto  
+  
+syntax = "proto3";  
+  
+package words.v1;  
+  
+option go_package = "proxima/app/word/api/words/v1";  
+  
+import "pbentity/words.proto";  
+  
+service Words{  
+  rpc Create(CreateReq) returns (CreateRes) {}  
+  rpc Get(GetReq) returns (GetRes) {}  
+}  
+  
+message CreateReq {  
+  uint32 uid = 1; // v:required  
+  string word = 2; // v:required  
+  string definition = 3; // v:required  
+}  
+  
+message CreateRes {  
+  uint32 id = 1;  
+}  
+  
+message GetReq {  
+  uint32 id = 1; // v:required  
+}  
+  
+message GetRes {  
+  pbentity.Words words = 1;  
+}
+```

docs/course/proxima-book/第三张-单词服务/3.4.控制器.md

@@ -0,0 +1,55 @@
+执行命令
+
+```bash
+$ gf gen pb
+```
+
+*app/word/internal/controller/words/words.go*
+```go
+package words  
+
+import (  
+    "context"  
+
+    "proxima/app/word/api/pbentity"
+    v1 "proxima/app/word/api/words/v1"  
+    "proxima/app/word/internal/logic/words"  
+    "github.com/gogf/gf/contrib/rpc/grpcx/v2"
+)
+
+type Controller struct {  
+    v1.UnimplementedWordsServer  
+}  
+
+func Register(s *grpcx.GrpcServer) {  
+    v1.RegisterWordsServer(s.Server, &Controller{})  
+}  
+
+func (*Controller) Create(ctx context.Context, req *v1.CreateReq) (res *v1.CreateRes, err error) {  
+    id, err := words.Create(ctx)  
+    if err != nil {  
+       return nil, err  
+    }  
+    return &v1.CreateRes{Id: uint32(id)}, nil  
+}  
+
+func (*Controller) Get(ctx context.Context, req *v1.GetReq) (res *v1.GetRes, err error) {  
+    data, err := words.Get(ctx)  
+    if err != nil {  
+       return nil, err  
+    }  
+    return &v1.GetRes{  
+       Words: &pbentity.Words{  
+          Id:                 uint32(data.Id),  
+          Uid:                uint32(data.Uid),  
+          Word:               data.Word,  
+          Definition:         data.Definition,  
+          ExampleSentence:    data.ExampleSentence,  
+          ChineseTranslation: data.ChineseTranslation,  
+          Pronunciation:      data.Pronunciation,  
+          CreatedAt:          timestamppb.New(data.CreatedAt.Time),  
+          UpdatedAt:          timestamppb.New(data.CreatedAt.Time),  
+       },  
+    }, nil  
+}
+```

docs/course/proxima-book/第三张-单词服务/3.5.启动运行.md

@@ -0,0 +1,125 @@
+## cmd引入控制器
+---
+和单体服务一样，微服务也需要在`cmd`中引入。
+
+*app/word/internal/cmd/cmd.go*
+```go
+package cmd  
+
+import (  
+    "context"  
+
+    "github.com/gogf/gf/contrib/rpc/grpcx/v2"
+    "github.com/gogf/gf/v2/os/gcmd"
+    "google.golang.org/grpc"
+    "proxima/app/word/internal/controller/words"
+)  
+
+var (  
+    Main = gcmd.Command{  
+       Name:  "main",  
+       Usage: "main",  
+       Brief: "word grpc service",  
+       Func: func(ctx context.Context, parser *gcmd.Parser) (err error) {  
+          c := grpcx.Server.NewConfig()  
+          c.Options = append(c.Options, []grpc.ServerOption{  
+             grpcx.Server.ChainUnary(  
+                grpcx.Server.UnaryValidate,  
+             )}...,  
+          )  
+          s := grpcx.Server.New(c)  
+          words.Register(s)  
+          s.Run()  
+          return nil  
+       },  
+    }  
+)
+```
+
+## 主入口文件
+---
+在入库文件内引入数据库驱动和`cmd`。
+
+*app/user/main.go*
+```go
+package main  
+
+import (  
+    "github.com/gogf/gf/v2/os/gctx"  
+    "proxima/app/word/internal/cmd"
+    _ "proxima/app/word/internal/packed"  
+)  
+
+func main() {  
+    cmd.Main.Run(gctx.GetInitCtx())  
+}
+```
+
+## 配置文件
+---
+*app/user/manifest/config/config.yaml*
+```go
+grpc:  
+  name:             "word"
+  address:          ":32002"
+
+database:  
+  default:  
+    link:  "mysql:root:12345678@tcp(srv.com:3306)/word"  
+    debug: true
+```
+
+## 启动运行
+---
+确保依赖正常，运行单词微服务。
+
+```go
+$ cd app/word
+build: .\main.go
+go build -o .\main.exe  .\main.go
+.\main.exe 
+build running pid: 2416
+2024-12-09 15:10:40.546 [DEBU] {18cc6c8aa5700f18bf2deb5e3439664a} set default registry using file registry as no custom registry set, path: C:\Users\half\AppData\Local\Temp\gsvc
+2024-12-09 15:10:40.566 [DEBU] {18cc6c8aa5700f18bf2deb5e3439664a} service register: &{Head: Deployment: Namespace: Name:word Version: Endpoints:192.168.10.98:32002 Metadata:map[protocol:grpc]}
+2024-12-09 15:10:40.567 [INFO] {18cc6c8aa5700f18bf2deb5e3439664a} pid[2416]: grpc server started listening on [:32002]
+```
+
+至此，**比邻英语本**的第二个微服务开发完成，甚至略显啰嗦。
+
+测试结果展示：
+
+```json
+grpc 127.0.0.1:32002.words.v1.Words.Create
+{
+    "uid": 1,
+    "word": "hello",
+    "definition": "used as a greeting when you meet somebody."
+}
+{
+    "id": 1
+}
+
+grpc 127.0.0.1:32002.words.v1.Words.Get
+{
+    "id": 1
+}
+{
+    "words": {
+        "Id": 1,
+        "Uid": 1,
+        "Word": "hello",
+        "Definition": "used as a greeting when you meet somebody.",
+        "ExampleSentence": "Hello, I am oldme!",
+        "ChineseTranslation": "你好",
+        "Pronunciation": "həˈləʊ",
+        "CreatedAt": {
+            "seconds": "1733407200",
+            "nanos": 0
+        },
+        "UpdatedAt": {
+            "seconds": "1733407200",
+            "nanos": 0
+        }
+    }
+}
+```

docs/course/proxima-book/第二章-用户服务/2.1.前置准备.md

@@ -20,7 +20,7 @@ app/user/internal/controller/*
 app/user/internal/cmd/cmd.go
 ```
 
-代码完成后，我们就可以进入微服务仓库，开始正式的开发。
+代码完成后，我们就可以进入微服务仓库，开始正式开发。
 ```bash
 $ cd app/user
 ```

docs/course/proxima-book/第二章-用户服务/2.5.启动运行.md

@@ -60,8 +60,8 @@ func main() {
 *app/user/manifest/config/config.yaml*
 ```go
 grpc:  
-  name:             "user"        # 服务名称  
-  address:          ":32001"      # 自定义服务监听地址  
+  name:             "user"
+  address:          ":32001"
 
 database:  
   default:  
@@ -80,7 +80,7 @@ $ cd ../../
 go mod tidy
 ```
 
-回到微服务仓库，正式运行微服务项目。
+回到微服务仓库，正式运行用户微服务。
 
 ```go
 $ cd app/user