microservice tutorial

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

@@ -0,0 +1,37 @@
+---
+slug: '/course/proxima-book'
+title: '微服务实战教程-比邻英语本'
+hide_title: true
+sidebar_position: 1
+keywords: [GoFrame,GoFrame框架,比邻英语本,微服务,gRPC,etcd,服务注册,GoFrame微服务,Golang微服务,Golang教程,编程技巧,项目开发,程序员入门,技术栈,软件开发,计算机科学]
+description: '本书通过GoFrame框架，以比邻英语本项目实战为例，帮助读者快速掌握GoFrame微服务开发。适合已经对`GoFrame`小有所成，希望进一步掌握微服务开发的朋友。'
+---
+
+## 本书简介
+---
+**比邻英语本**是 GoFrame 中级实战教程。与初级教程[星辰英语本](https://goframe.org/course/starbook)不同，**微服务**开发是本书的主旋律。
+
+## 编写本书的动机
+---
+网上的教程总是哐当一下，甩出各类技术名词、成吨的架构分层，或者不明觉厉的一大段说明。看的人眼花缭乱，往往花了很久的时间，读了一大堆文章，也没能写出一行代码。
+
+所以呐，耳闻之不如目见之，目见之不如足践之。实际操作才是掌握微服务的良药，本书将从`GoFrame`框架出发，开发出一个实际的微服务项目，揭开它神秘的面纱。最终您会发现，微服务的开发是一件很简单的事情。当然，这并不是说微服务很简单，只是它的复杂度不是来源于开发，而是微服务治理。
+
+以实际项目为导向，分享更多专业、实用的编程技巧和经验，让您学有所成是作者的期望！
+
+## 目标读者
+---
+已经对`GoFrame`小有所成，希望进一步掌握微服务开发的朋友。
+
+## 联系作者
+---
+在编写本书的过程中，不可避免的会有一些错误或者不足之处，如果您有任何问题或者建议，可以在下方留言，也可以联系我，我会尽快回复您！
+- 邮箱: `[email protected]` `[email protected]`
+- 网站: [https://oldme.net](https://oldme.net)
+- 微信: `NobodyIsRight` 来者请备注来意哦！
+
+## 遇到问题
+---
+在开发中，遇到各种问题都是正常的。如何解决问题才是关键，在遇到问题时，请先尝试自行解决。查阅`GoFrame`文档，使用搜索引擎都是不错的解决问题的方式。如果实在无法解决，可以联系我，我会尽力帮助您解决问题。
+
+import DocCardList from '@theme/DocCardList';

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

@@ -0,0 +1,37 @@
+---
+title: '1.1.写作约定'
+hide_title: true
+slug: '/course/proxima-book/about-convention'
+keywords: [GoFrame, proxima-book, writing convention, code examples, command line usage, code simplification, microservices development]
+description: "本章介绍了 GoFrame 微服务教程的写作约定，包括代码示例的简化原则、命令行使用规范和代码省略说明，帮助读者更好地理解教程内容。"
+---
+
+## 代码从简
+---
+能看到本书，就说明您已经是代码江湖上颇具水平的老鸟了。所以，我也会减少不必要的啰嗦，跳过不必要的代码细节，**只着重展示微服务的开发流程与特性。**
+
+## 命令行
+---
+本书会在一些地方使用命令行，我将使用 `$` 符号作为提示符，您不需要输入这个符号。比如，如果我写了 `$ echo "Hello, GoFrame!" `，您只需要输入 `echo "Hello, GoFrame!" ` 即可。
+
+```bash
+$ echo "Hello, GoFrame!"
+Hello, GoFrame!
+```
+
+## 代码省略
+---
+为了保证篇幅的整洁，在不必要的竖版代码中，我会使用`...`来省略代码。
+
+```go
+package main
+
+import "fmt"
+
+...
+
+func main() {
+    fmt.Println("Hello GoFrame")
+}
+
+...

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

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

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

@@ -0,0 +1,97 @@
+---
+title: '1.3.环境准备'
+hide_title: true
+slug: '/course/proxima-book/about-prepare'
+keywords: [GoFrame, gRPC, Protocol Buffers, development environment, installation guide, etcd, microservices tools, Go installation]
+description: "详细介绍了开发 GoFrame 微服务项目所需的环境准备工作，包括 Go 语言环境配置、GoFrame 框架安装、gRPC 工具链配置以及相关依赖组件的安装说明。"
+---
+
+如果您的版本和我不一致，也无需担心，他们基本是共通的。
+
+## GoFrame
+---
+`Golang`和`GoFrame`的安装方式不再赘述。这里使用的版本信息如下：
+- `go version go1.23.4 windows/amd64`
+- `goframe v2.8.2`
+
+## 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` 文件定义消息结构，然后通过编译器生成相应语言的代码。
+
+根据不同的操作系统，在 [Protocal Release](https://github.com/protocolbuffers/protobuf/releases) 下载对应的文件安装。如果是 `MacOS` 环境，可以使用 `brew` 工具安装依赖：
+
+```bash
+$ brew install grpc protoc-gen-go protoc-gen-go-grpc
+```
+
+检测是否安装成功。
+```bash
+$protoc --version
+libprotoc 26.1
+```
+
+## etcd
+---
+etcd 是一个分布式键值存储系统，常用于分布式系统中的服务发现。安装它有多种方式，这里贴出
+`docker-compose.yaml`文件用作参考。
+
+```yaml
+version: "3.7"
+
+services:
+    etcd:
+        image: "bitnami/etcd:3.5"
+        container_name: "etcd"
+        restart: "always"
+        ports:
+            - 2379:2379
+        environment:
+            - TZ=Asia/Shanghai
+            - ALLOW_NONE_AUTHENTICATION=yes
+            - ETCD_ADVERTISE_CLIENT_URLS=http://etcd:2379
+```
+
+如果安装成功，在浏览器访问 [http://IP:2379/version](http://IP:2379/version)，会出现以下信息：
+```json
+{"etcdserver": "3.5.17","etcdcluster": "3.5.0"}
+```
+
+如果您想更酷一些，安装个`etcd`集群或者学习一下`etcd`的基础使用，可以参考[此文](https://oldme.net/article/32)。
+
+## 数据库
+--- 
+`MySQL`的安装不必多说，使用其他数据库亦可。
+
+需要注意的是，微服务架构下，每个单独的服务都应当有自己的数据库。所以，我们需要建立两个数据库，名称分别是`user`和`word`。
+
+```sql
+CREATE DATABASE user;
+CREATE DATABASE word;

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

@@ -0,0 +1,70 @@
+---
+title: '1.4.项目初始化'
+hide_title: true
+slug: '/course/proxima-book/about-init'
+keywords: [GoFrame, project initialization, Monorepo, project structure, dependency management, go.mod, microservices setup]
+description: "详细说明了如何使用 GoFrame CLI 工具初始化微服务项目，包括创建 Monorepo 仓库、配置依赖版本、设置项目结构等关键步骤。"
+---
+
+## 初始化仓库
+---
+执行命令，初始化一个名为`proxima`的`Monorepo`仓库：
+
+```bash
+$ gf init proxima -m
+```
+
+修改`go`语言的最低依赖版本为当前环境，确保大于`GoFrame`最低版本要求即可。
+
+*go.mod*
+```text
+module proxima  
+
+go 1.23.4
+```
+
+`GoFrame`升级到最新版本：
+```bash
+$ cd proxima
+gf up
+```
+
+删除不必要的示例文件：
+```bash
+$ rm -rf app/*
+```
+
+完成后的项目结构：
+```text
+app
+hack
+    hack.mk
+    hack-cli.mk
+utility
+go.mod
+go.sum
+```
+
+在`Monorepo`仓库模式下，根目录只提供对项目依赖管理，不存在`main.go`文件。
+
+`app`目录保存微服务各自的代码文件，例如`app/user/main.go`，`app/word/main.go`。
+
+## 安装微服务组件
+---
+安装`grpcx`组件，让`GoFrame`支持微服务开发。
+```bash
+$ go get -u github.com/gogf/gf/contrib/rpc/grpcx/v2
+```
+
+## 安装数据库驱动
+---
+和单体服务一样，也需要安装对应的数据库驱动，这里演示的是`MySQL`。
+```bash
+$ go get -u github.com/gogf/gf/contrib/drivers/mysql/v2
+```
+
+## 安装etcd组件
+---
+安装`etcd`组件，提供服务注册功能。
+```bash
+$ go get -u github.com/gogf/gf/contrib/registry/etcd/v2

docs/course/proxima-book/第一章-基础信息/1.5.本书源码.md

@@ -0,0 +1,34 @@
+---
+title: '1.5.本书源码'
+hide_title: true
+slug: '/course/proxima-book/about-source'
+keywords: [GoFrame, source code, GitHub repository, MIT license, open source, proxima project]
+description: "提供了本教程项目的源代码获取方式，包括 GitHub 仓库地址和 MIT 开源许可证的详细说明。"
+---
+
+本书的源码开源在 [https://github.com/oldme-git/proxima](https://github.com/oldme-git/proxima)。
+
+开源许可证基于`MIT`协议：
+```text
+MIT License  
+
+Copyright (c) 2024 oldme  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy  
+of this software and associated documentation files (the "Software"), to deal  
+in the Software without restriction, including without limitation the rights  
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+copies of the Software, and to permit persons to whom the Software is  
+furnished to do so, subject to the following conditions:  
+
+The above copyright notice and this permission notice shall be included in all  
+copies or substantial portions of the Software.  
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  
+SOFTWARE.
+```

docs/course/proxima-book/第一章-基础信息/第一章-基础信息.md

@@ -0,0 +1,20 @@
+---
+title: '第一章-基础信息'
+hide_title: true
+sidebar_position: 1
+slug: '/course/proxima-book/about'
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
+
+
+
+
+
+
+
+
+
+