add REAME

.github/RELEASE.md

@@ -1,5 +1,5 @@
 ## Change log
 
-1. Change page field size to limit.
-2. Supporting custom bingdingXXX and response in the web(protobuf).
-3. Match message name xxxID in the protobuf file.
+1. Modify the returned ID type, it will affect the ID types of GetByID and List for `⓵Create web service based on sql`, which are consistent with the ID types in the database.
+
+> If you are using code for `⓵Create web service based on sql` before v1.8.6, do not modify the sponge version under go.mod and upgrade to v1.8.6 or above. Otherwise, the List interface will return empty data because the original `size` field has become invalid (replaced by `limit` field).

pkg/grpc/metrics/monitor-example-cn.md

@@ -0,0 +1,174 @@
+### 启动Prometheus和Grafana服务
+
+**(1) prometheus服务**
+
+这是 [prometheus服务启动脚本](https://github.com/zhufuyi/sponge/tree/main/test/server/monitor/prometheus)，启动prometheus服务：
+
+```bash
+docker-compose up -d
+```
+
+在浏览器访问prometheus主页 [http://localhost:9090](http://localhost:9090/) 。
+
+<br>
+
+**(2) grafana服务**
+
+这是 [grafana服务启动脚本](https://github.com/zhufuyi/sponge/tree/main/test/server/monitor/grafana)，启动grafana服务：
+
+```bash
+docker-compose up -d
+```
+
+在浏览器访问 grafana 主页面 [http://localhost:33000](http://localhost:33000) ，设置prometheus的数据源 `http://localhost:9090` 。
+
+> [!attention] 在grafana导入监控面板的json的**datasource**值，必须与在grafana设置的prometheus的数据源名称(这里是**Prometheus**)要一致，否则图标上无法显示数据。
+
+<br>
+
+### web服务监控示例
+
+以`⓵基于sql创建web服务`代码为例，默认提供指标接口 [http://localhost:8080/metrics](http://localhost:8080/metrics) 。
+
+**(1) 在prometheus添加监控目标**
+
+打开prometheus配置文件`prometheus.yml`，添加采集目标：
+
+```bash
+  - job_name: 'http-edusys'
+    scrape_interval: 10s
+    static_configs:
+      - targets: ['localhost:8080']
+```
+
+> [!attention] 在启动Prometheus服务前，必须将文件`prometheus.yml`权限改为`0777`，否则使用vim修改`prometheus.yml`文件无法同步到容器中。
+
+执行请求使prometheus配置生效 `curl -X POST http://localhost:9090/-/reload` ，稍等一会，然后在浏览器访问 [http://localhost:9090/targets](http://localhost:9090/targets)，检查新添加的采集目标是否生效。
+
+<br>
+
+**(2) 在grafana添加监控面板**
+
+把 [http 监控面板](https://github.com/zhufuyi/sponge/blob/main/pkg/gin/middleware/metrics/gin_grafana.json) 导入到grafana，如果监控界面没有数据显示，检查json里的数据源名称与grafana配置prometheus数据源名称是否一致。
+
+<br>
+
+**(3) 压测接口，观察监控数据**
+
+使用[wrk](https://github.com/wg/wrk)工具压测接口
+
+```bash
+# 接口1
+wrk -t2 -c10 -d10s http://192.168.3.27:8080/api/v1/teacher/1
+
+# 接口2
+wrk -t2 -c10 -d10s http://192.168.3.27:8080/api/v1/course/1
+```
+
+监控界面如下图所示：
+
+![http-grafana](https://go-sponge.com/assets/images/http-grafana.jpg)
+
+<br>
+
+### grpc服务监控示例
+
+以`⓶基于sql创建grpc服务`代码为例，默认提供指标接口 [http://localhost:8283/metrics](http://localhost:8283/metrics) 。
+
+**(1) 在prometheus添加监控目标**
+
+打开prometheus配置文件`prometheus.yml`，添加采集目标：
+
+```yaml
+  - job_name: 'rpc-server-user'
+    scrape_interval: 10s
+    static_configs:
+      - targets: ['localhost:8283']
+```
+
+> [!attention] 在启动Prometheus服务前，必须将文件`prometheus.yml`权限改为`0777`，否则使用vim修改`prometheus.yml`文件无法同步到容器中。
+
+执行请求使prometheus配置生效 `curl -X POST http://localhost:9090/-/reload` ，稍等一会，然后在浏览器访问 [http://localhost:9090/targets](http://localhost:9090/targets)， 检查新添加的采集目标是否生效。
+
+<br>
+
+**(2) 在grafana添加监控面板**
+
+把 [grpc server 监控面板](https://github.com/zhufuyi/sponge/blob/main/pkg/grpc/metrics/server_grafana.json) 导入到grafana，如果监控界面没有数据显示，检查json里的数据源名称与grafana配置prometheus数据源名称是否一致。
+
+<br>
+
+**(3) 压测grpc api，观察监控数据**
+
+使用`Goland` IDE打开`internal/service/teacher_client_test.go`文件，对**Test_teacherService_methods** 或 **Test_teacherService_benchmark** 下各个方法进行测试。
+
+监控界面如下图所示。
+![rpc-grafana](https://go-sponge.com/assets/images/rpc-grafana.jpg)
+
+<br>
+
+上面是grpc服务端的监控，grpc的客户端的监控也类似，[grpc client 监控面板](https://github.com/zhufuyi/sponge/blob/main/pkg/grpc/metrics/client_grafana.json) 。
+
+<br>
+
+### 在prometheus自动添加和移除监控目标
+
+实际使用中服务数量比较多，手动添加监控目标到prometheus比较繁琐，也容易出错。prometheus支持使用`consul`的服务注册与发现进行动态配置，自动添加和移除监控目标。
+
+在本地启动 consul 服务，这是 [consul 服务启动脚本](https://github.com/zhufuyi/sponge/tree/main/test/server/consul)，启动consul服务：
+
+```bash
+docker-compose up -d
+```
+
+打开 prometheus 配置 prometheus.yml，添加consul配置：
+
+```yaml
+  - job_name: 'consul-micro-exporter'
+    consul_sd_configs:
+      - server: 'localhost:8500'
+        services: []  
+    relabel_configs:
+      - source_labels: [__meta_consul_tags]
+        regex: .*user.*
+        action: keep
+      - regex: __meta_consul_service_metadata_(.+)
+        action: labelmap
+```
+
+执行请求使prometheus配置生效 `curl -X POST http://localhost:9090/-/reload` 。
+
+在prometheus配置好consul服务发现之后，接着把服务的地址信息推送到consul，推送信息 user_exporter.json 文件内容如下：
+
+```json
+{
+  "ID": "user-exporter",
+  "Name": "user",
+  "Tags": [
+    "user-exporter"
+  ],
+  "Address": "localhost",
+  "Port": 8283,
+  "Meta": {
+    "env": "dev",
+    "project": "user"
+  },
+  "EnableTagOverride": false,
+  "Check": {
+    "HTTP": "http://localhost:8283/metrics",
+    "Interval": "10s"
+  },
+  "Weights": {
+    "Passing": 10,
+    "Warning": 1
+  }
+}
+```
+
+> curl -XPUT --data @user_exporter.json http://localhost:8500/v1/agent/service/register
+
+稍等一会，然后在浏览器打开 [http://localhost:9090/targets](http://localhost:9090/targets)  检查新添加的采集目标是否生效。然后关闭服务，稍等一会，检查是否自动移除采集目标。
+
+> [!tip] 在web或grpc务中，通常是使用程序代码自动把json信息提交给consul，不是通过命令，web或grpc务正常启动服务后，Prometheus就可以动态获取到监控目标，web或grpc务停止后，Prometheus自动移除监控目标。
+
+<br>

pkg/grpc/metrics/monitor-example-en.md

@@ -0,0 +1,175 @@
+### Starting Prometheus and Grafana Services
+
+**(1) Prometheus Service**
+
+Here is the [script for starting the Prometheus service](https://github.com/zhufuyi/sponge/tree/main/test/server/monitor/prometheus). Start the Prometheus service:
+
+```bash
+docker-compose up -d
+```
+
+Access the Prometheus homepage in your browser at [http://localhost:9090](http://localhost:9090/).
+
+<br>
+
+**(2) Grafana Service**
+
+Here is the [script for starting the Grafana service](https://github.com/zhufuyi/sponge/tree/main/test/server/monitor/grafana). Start the Grafana service:
+
+```bash
+docker-compose up -d
+```
+
+Access the main Grafana page in your browser at [http://localhost:33000](http://localhost:33000), and configure the Prometheus data source to be `http://localhost:9090`.
+
+> [!attention] When importing JSON dashboards into Grafana, the **datasource** value in the JSON must match the name of the Prometheus data source you set in Grafana (in this case, **Prometheus**), or the graphs won't display data.
+
+<br>
+
+### Web Service Monitoring Example
+
+Taking the code for the `⓵ Web Service Based on SQL` as an example, it provides a default metrics interface at [http://localhost:8080/metrics](http://localhost:8080/metrics).
+
+**(1) Adding Monitoring Targets to Prometheus**
+
+Open the Prometheus configuration file `prometheus.yml` and add scraping targets:
+
+```bash
+  - job_name: 'http-edusys'
+    scrape_interval: 10s
+    static_configs:
+      - targets: ['localhost:8080']
+```
+
+> [!attention] Before starting the Prometheus service, make sure to change the permissions of the `prometheus.yml` file to `0777`. Otherwise, changes made to `prometheus.yml` using `vim` won't be synchronized with the container.
+
+Trigger the Prometheus configuration to take effect by executing `curl -X POST http://localhost:9090/-/reload`. Wait for a moment, then access [http://localhost:9090/targets](http://localhost:9090/targets) in your browser to check if the newly added scraping target is active.
+
+<br>
+
+**(2) Adding Monitoring Dashboards to Grafana**
+
+Import the [HTTP monitoring dashboard](https://github.com/zhufuyi/sponge/blob/main/pkg/gin/middleware/metrics/gin_grafana.json) into Grafana. If the monitoring interface does not display data, check if the data source name in the JSON matches the Prometheus data source name in Grafana's configuration.
+
+<br>
+
+**(3) Load Testing the API and Observing Monitoring Data**
+
+Use the [wrk](https://github.com/wg/wrk) tool to perform load testing on the API:
+
+```bash
+# test 1
+wrk -t2 -c10 -d10s http://192.168.3.27:8080/api/v1/teacher/1
+
+# test 2
+wrk -t2 -c10 -d10s http://192.168.3.27:8080/api/v1/course/1
+```
+
+The monitoring interface will look like the following image:
+
+![http-grafana](https://go-sponge.com/assets/images/http-grafana.jpg)
+
+<br>
+
+### GRPC Service Monitoring Example
+
+Taking the code for the `⓶Create grpc service based on sql` as an example, it provides a default metrics interface at [http://localhost:8283/metrics](http://localhost:8283/metrics).
+
+**(1) Adding Monitoring Targets to Prometheus**
+
+Open the Prometheus configuration file `prometheus.yml` and add scraping targets:
+
+```yaml
+  - job_name: 'rpc-server-user'
+    scrape_interval: 10s
+    static_configs:
+      - targets: ['localhost:8283']
+```
+
+> [!attention] Before starting the Prometheus service, make sure to change the permissions of the `prometheus.yml` file to `0777`. Otherwise, changes made to `prometheus.yml` using `vim` won't be synchronized with the container.
+
+Trigger the Prometheus configuration to take effect by executing `curl -X POST http://localhost:9090/-/reload`. Wait for a moment, then access [http://localhost:9090/targets](http://localhost:9090/targets) in your browser to check if the newly added scraping target is active.
+
+<br>
+
+**(2) Adding Monitoring Dashboards to Grafana**
+
+Import the [grpc service monitoring dashboard](https://github.com/zhufuyi/sponge/blob/main/pkg/grpc/metrics/server_grafana.json) into Grafana. If the monitoring interface does not display data, check if the data source name in the JSON matches the Prometheus data source name in Grafana's configuration.
+
+<br>
+
+**(3) Load Testing GRPC Methods and Observing Monitoring Data**
+
+Open the `internal/service/teacher_client_test.go` file using the `Goland` IDE and test various methods under **Test_teacherService_methods** or **Test_teacherService_benchmark**.
+
+The monitoring interface will look like the following image:
+
+![rpc-grafana](https://go-sponge.com/assets/images/rpc-grafana.jpg)
+
+<br>
+
+The monitoring for the grpc client is similar to the server monitoring, and you can find the [grpc client monitoring dashboard](https://github.com/zhufuyi/sponge/blob/main/pkg/grpc/metrics/client_grafana.json) here.
+
+<br>
+
+### Automatically Adding and Removing Monitoring Targets in Prometheus
+
+In real-world scenarios, managing monitoring targets in Prometheus manually can be cumbersome and error-prone, especially when dealing with a large number of services. Prometheus supports dynamic configuration using service discovery with tools like `Consul` to automatically add and remove monitoring targets.
+
+Start a local Consul service using the [Consul service start script](https://github.com/zhufuyi/sponge/tree/main/test/server/consul):
+
+```bash
+docker-compose up -d
+```
+
+Open the Prometheus configuration file `prometheus.yml` and add Consul configuration:
+
+```yaml
+  - job_name: 'consul-micro-exporter'
+    consul_sd_configs:
+      - server: 'localhost:8500'
+        services: []  
+    relabel_configs:
+      - source_labels: [__meta_consul_tags]
+        regex: .*user.*
+        action: keep
+      - regex: __meta_consul_service_metadata_(.+)
+        action: labelmap
+```
+
+Trigger the Prometheus configuration to take effect by executing `curl -X POST http://localhost:9090/-/reload`.
+
+Once you've configured Prometheus with Consul service discovery, you can push service address information to Consul. Push the information using a JSON file named `user_exporter.json` with content like this:
+
+```json
+{
+  "ID": "user-exporter",
+  "Name": "user",
+  "Tags": [
+    "user-exporter"
+  ],
+  "Address": "localhost",
+  "Port": 8283,
+  "Meta": {
+    "env": "dev",
+    "project": "user"
+  },
+  "EnableTagOverride": false,
+  "Check": {
+    "HTTP": "http://localhost:8283/metrics",
+    "Interval": "10s"
+  },
+  "Weights": {
+    "Passing": 10,
+    "Warning": 1
+  }
+}
+```
+
+> curl -XPUT --data @user_exporter.json http://localhost:8500/v1/agent/service/register
+
+Wait for a moment, then open [http://localhost:9090/targets](http://localhost:9090/targets) in your browser to check if the newly added scraping target is active. Then, stop the service and wait for a moment to check if the target is automatically removed.
+
+> [!tip] In web or grpc service, the JSON information is usually submitted to Consul automatically via program code, not through commands. After the web or grpc service starts normally, Prometheus can dynamically discover monitoring targets. When the web or grpc service stops, Prometheus automatically removes the monitoring target.
+
+<br>