proxima

docs/course/proxima-book/proxima-book.md

@@ -2,26 +2,16 @@
 ---
 **比邻英语本**是 GoFrame 中级实战教程。与初级教程[星辰英语本](https://goframe.org/course/starbook)不同，**微服务**开发是本书的主旋律。
 
-网上的教程总是哐当一下，甩出各类技术名词，成吨的架构分层等等，看的人眼花缭乱。花了很久的时间，看了一大堆文章，也没能写出一行代码。
+网上的教程总是哐当一下，甩出各类技术名词、成吨的架构分层，或者不明觉厉的一些说明。看的人眼花缭乱，花了很久的时间，读了一大堆文章，也没能写出一行代码。
 
-本书旨在抽丝剥茧，将复杂的微服务体系理明白，说清楚。从`GoFrame`框架出发，带领朋友们实际开发一个微服务项目，看看微服务究竟是怎么回事。
+所以呐，耳闻之不如目见之，目见之不如足践之。实际操作才是掌握微服务的良药，本书将从`GoFrame`框架出发，开发出一个实际的微服务项目，逐步揭开它神秘的面纱。
 
 以实际项目为导向，分享更多专业、实用的编程技巧和经验，让您学有所成是作者的期望！
 
 ## 目标读者
 ---
 已经对`GoFrame`小有所成，希望进一步掌握微服务开发的朋友。
 
-## 代码从简
----
-代码江湖上，您已经是颇具水平的老鸟了。我也不会向您展示不必要的业务代码细节，**只是着重展示微服务的开发流程与特性。**
-
-## 阅读建议
----
-本书是一本操作向的书籍，唯一的建议就是跟着书籍一步一步的操作。耳闻之不如目见之，目见之不如足践之。
-
-在跟着本书操作过程中，最好结合[官方开发手册](https://goframe.org/docs/design)，尝试举一反三，才能更好的理解和掌握。
-
 ## 联系作者
 ---
 在编写本书的过程中，不可避免的会有一些错误或者不足之处，如果你有任何问题或者建议，可以在下方留言，也可以联系我，我会尽快回复你！

docs/course/proxima-book/第一章-基础信息/1.1.写作约定.md

@@ -1,3 +1,7 @@
+## 代码从简
+---
+能看到本书，就说明您已经是代码江湖上颇具水平的老鸟了。所以，我也会减少不必要的啰嗦，跳过不必要的代码细节，**只着重展示微服务的开发流程与特性。**
+
 ## 命令行
 ---
 本书会在一些地方使用命令行，我将使用 `$` 符号作为提示符，你不需要输入这个符号。比如，如果我写了 `$ echo "Hello, GoFrame!" `，你只需要输入 `echo "Hello, GoFrame!" ` 即可。
@@ -7,8 +11,6 @@ $ echo "Hello, GoFrame!"
 Hello, GoFrame!
 ```
 
-`echo` 是一个输出命令，它会将 `Hello, GoFrame!` 输出到终端。
-
 ## 代码省略
 ---
 为了保证篇幅的整洁，在不必要的竖版代码中，我会使用`...`来省略代码。

docs/course/proxima-book/第一章-基础信息/1.2.架构介绍.md

@@ -0,0 +1,25 @@
+**比邻英语本**是一个帮助用户学习英语单词的轻量级软件，它包含以下业务功能：
+- 用户注册；
+- 用户登录；
+- 用户信息查询；
+- 单词的增删改查。
+
+我们将这些服务简单地拆分，将同类功能放在一起，演化出两个微服务：
+- 用户服务：处理用户注册、登录、信息查询等功能；
+- 单词服务：提供单词相关的功能，比如增删改查。
+
+微服务不直接对外提供服务，而是统一交由网关处理。网关作为一个`Web`服务，它不直接提供具体的业务功能，而是负责接收请求，转发到各微服务，最后拼接数据返回，以此来完成业务功能。
+
+网关的功能不仅限于协议转换，还包括负载均衡、认证授权、日志记录、监控和限流等。微服务之间通常使用`HTTP`或`gRPC`进行通讯。
+
+本书微服务采用`gRPC`协议。
+
+![](../assets/architecture.png)
+
+## 代码仓库
+---
+微服务将单体服务拆开，代码也自然分离。它的代码仓库，有两种常见的管理方式：
+- **Polyrepo：** 多仓库模式，每个微服务都有独立的仓库。优点是每个仓库相对较小，易于管理。缺点是需要额外的工具，流程协调各个服务之间的依赖和版本。
+- **Monorepo：** 单一仓库模式，所有微服务的代码都存放在一个仓库中。优点是可以统一管理版本和依赖，缺点是仓库可能会变得庞大，管理复杂度增加。
+
+我们的项目采用`Monorepo`模式。`Polyrepo`模式下一个服务一个目录，无需多言。

docs/course/proxima-book/第一章-基础信息/1.3.环境准备.md

@@ -1,26 +1,42 @@
-## 测试工具
----
-`gRPC`接口开发完成后，需要使用一些测试工具来测试是否正常运行。比较流行的测试工具有`Postman`、`Apifox`、`Apipost`等，它们大同小异，你可以根据自己的喜好选择一个。
-
-本书以文本行展示测试结果，例如：
-```text
-{
-    "Username": "oldme_1",
-    "Password": "12345678"
-}
-```
+如果你的版本和我不一致，也无需担心，他们基本是共通的。
 
 ## GoFrame
 ---
 `Golang`和`GoFrame`的安装方式不再赘述。这里使用的版本信息如下：
-- `go version go1.22.2 windows/amd64`
+- `go version go1.23.4 windows/amd64`
 - `goframe v2.8.1`
 
-> 如果你的版本和我不一致，也无需担心，`Go`和`GoFrame`都有着强大的向下兼容性。
+## gRPC
+---
+`gRPC`是一个由 `Google` 开发的远程过程调用（RPC）框架，基于`HTTP/2`。它使用 `Protocol` 作为默认的序列化格式。
+
+`Go`语言通过`gRPC-go`插件提供`gRPC`功能。执行命令安装插件：
+```bash
+$ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
+```
+
+### gRPC测试工具
+`gRPC`接口开发完成后，需要一些测试工具，来检测它是否正常运行。比较流行的测试工具有`Postman`、`Apifox`、`Apipost`等，它们大同小异，你可以根据自己的喜好选择一个。
+
+本书统一使用`json`展示测试结果，例如：
+```json
+grpc 127.0.0.1:32001.account.v1.Account.UserRegister
+{
+    "username": "oldme",
+    "password": "123456",
+    "email": "[email protected]"
+}
+{
+    "id": 1
+}
+```
+
+它们分别代表请求地址，请求参数，响应参数。
 
 ## Protocol
 ---
- `Protocol` 是 Google 设计的数据序列化格式，用于结构化数据的序列化和反序列化。使用 `.proto` 文件定义消息结构，然后通过编译器生成相应语言的代码。
+ `Protocol` 是 `Google` 设计的数据序列化格式，用于结构化数据的序列化和反序列化。使用 `.proto` 文件定义消息结构，然后通过编译器生成相应语言的代码。
 
 根据不同的操作系统，在 [Protocal Release](https://github.com/protocolbuffers/protobuf/releases) 下载对应的文件安装。如果是 `MacOS` 环境，可以使用 `brew` 工具安装依赖：
 
@@ -33,17 +49,6 @@ $ brew install grpc protoc-gen-go protoc-gen-go-grpc
 $protoc --version
 libprotoc 26.1
 ```
-版本只要不是相差太大，都无须担心。
-
-## gRPC
----
-`gRPC`是一个由 Google 开发的远程过程调用（RPC）框架，基于HTTP/2。它使用 `Protocol` 作为默认的序列化格式。可以理解为 `HTTP` 和 `JSON` 的关系。
-
-`Go`语言通过`gRPC-go`插件提供`gRPC`功能。执行命令安装插件：
-```bash
-$ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
-go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
-```
 
 ## etcd
 ---
@@ -57,37 +62,31 @@ services:
     etcd:
         image: "bitnami/etcd:3.5"
         container_name: "etcd"
-        # 总是重启
         restart: "always"
         ports:
             - 2379:2379
         environment:
-            # 时区设置
             - TZ=Asia/Shanghai
             # 允许无认证访问
             - ALLOW_NONE_AUTHENTICATION=yes
             # etcd 客户端访问URL
             - ETCD_ADVERTISE_CLIENT_URLS=http://etcd:2379
-        volumes:
-            # 将数据映射到宿主机
-            - etcd_data:/bitnami/etcd
-
-volumes:
-    etcd_data:
-        driver: local
-        driver_opts:
-            type: "none"
-            o: "bind"
-            device: "/home/docker/etcd/data"
 ```
 
 如果安装成功，在浏览器访问 [http://IP:2379/version](http://IP:2379/version)，会出现以下信息：
 ```json
 {"etcdserver": "3.5.17","etcdcluster": "3.5.0"}
 ```
 
-如果你更酷一些，安装个`etcd`集群或者学习一下`etcd`的基础使用，可以参考[此文](https://oldme.net/article/32)。
+如果你想更酷一些，安装个`etcd`集群或者学习一下`etcd`的基础使用，可以参考[此文](https://oldme.net/article/32)。
 
 ## 数据库
 --- 
-`MySQL`的安装不必多说，使用其他数据库亦可。
+`MySQL`的安装不必多说，使用其他数据库亦可。
+
+需要注意的是，微服务架构下，每个单独的服务都应当有自己的数据库。所以，我们需要建立两个数据库，名称分别是`user`和`word`。
+
+```sql
+CREATE DATABASE user;
+CREATE DATABASE word;
+```

docs/course/proxima-book/第一章-基础信息/1.4.项目初始化.md

@@ -1,15 +1,24 @@
 ## 初始化仓库
 ---
-执行命令，初始化一个名为`proxima`的微服务仓库：
+执行命令，初始化一个名为`proxima`的`Monorepo`仓库：
 
 ```bash
 $ gf init proxima -m
 ```
 
+修改`go`语言的最低依赖版本，确保大于`GoFrame`最低版本要求即可。
+
+*go.mod*
+```text
+module proxima  
+  
+go 1.23.4
+```
+
 `GoFrame`升级到最新版本：
 ```bash
 $ cd proxima
-gf -up
+gf up
 ```
 
 删除不必要的示例文件：
@@ -27,16 +36,19 @@ utility
 go.mod
 go.sum
 ```
+
 在`Monorepo`仓库模式下，根目录只提供对项目依赖管理，不存在`main.go`文件。`app`目录下保存各微服务的代码文件，例如`app/user/main.go`，`app/word/main.go`。
 
-## 建立数据库
+## 安装微服务组件
 ---
-微服务架构下，每个单独的服务都应当有自己的数据库。所以，我们需要建立两个数据库，名称分别是`user`和`word`。
+安装`grpcx`组件，让`GoFrame`支持微服务开发。
+```bash
+$ go get -u github.com/gogf/gf/contrib/rpc/grpcx/v2
+```
 
 ## 安装数据库驱动
 ---
-和单体服务一样，也需要安装对应的数据库驱动，这里演示的是`MySQL`:
-
+和单体服务一样，也需要安装对应的数据库驱动，这里演示的是`MySQL`。
 ```bash
-go get -u github.com/gogf/gf/contrib/drivers/mysql/v2
+$ go get -u github.com/gogf/gf/contrib/drivers/mysql/v2
 ```