Merge pull request #26 from WGrape/testing

style: 添加方法注释和binlog数据处理过程文档等
WGrape · Dec 30, 2021 · 2681a2c · 2681a2c
2 parents ac62fde + e2061bb
commit 2681a2c
Show file tree

Hide file tree

Showing 16 changed files with 479 additions and 50 deletions.
diff --git a/HOWTOCODE.md b/HOWTOCODE.md
@@ -3,9 +3,10 @@
 - &nbsp;&nbsp;&nbsp;&nbsp;[1、基于Canal](#11)  
 - &nbsp;&nbsp;&nbsp;&nbsp;[2、ES文档更新](#12)
 - &nbsp;&nbsp;&nbsp;&nbsp;[3、完整架构](#13)
-- [二、执行原理](#2)
+- [二、底层原理](#2)
 - &nbsp;&nbsp;&nbsp;&nbsp;[1、生命周期](#21)
 - &nbsp;&nbsp;&nbsp;&nbsp;[2、命令执行](#22)
+- &nbsp;&nbsp;&nbsp;&nbsp;[3、binlog数据处理过程](#23)
 - [三、应用配置](#3)
 - &nbsp;&nbsp;&nbsp;&nbsp;[1、消费配置](#31)
 - &nbsp;&nbsp;&nbsp;&nbsp;[2、数据库配置](#32)
@@ -43,7 +44,7 @@ ESUpdater提供了从消费Kafka中的数据库增量数据，到ES文档增量
 
 <img src="https://user-images.githubusercontent.com/35942268/147027126-1df83ddf-8698-44dd-a988-5499f7eeb063.png" width="625">
 
-## <span id="2">二、执行原理</span>
+## <span id="2">二、底层原理</span>
 ESUpdater的核心由```Consumer```进程和```Worker```进程组成，其中根目录下的```/esupdater.php```为入口文件
 
 ### <span id="21">1、生命周期</span>
@@ -79,6 +80,15 @@ ESUpdater的核心由```Consumer```进程和```Worker```进程组成，其中根
 #### <span id="223">(3) work</span>
 当```Consumer```进程使用```php esupdater work```命令启动```Worker```进程时，```Worker```进程会记录下```/runtime/esupdater-worker-{pid}.pid```进程ID文件，只有当结束后才会删除此文件。
 
+### <span id="23">3、binlog数据处理过程</span>
+处理过程为```binlog => canalData => urlencode(canalData)```，可以参考文件 [/framework/Canal.php](./framework/Canal.php)
+
+1. Canal将```binlog```数据解析为```json```格式并投递至kafka
+2. Consumer进程消费kafka，使用```urlencode```方式编码获取到的消息数据
+3. Consumer进程把编码后的消息数据，传递至Worker进程
+4. Worker进程再依次拆解数据即可
+
+
 ## <span id="3">三、应用配置</span>
 
 ### <span id="31">1、消费配置</span>

diff --git a/README.md b/README.md
@@ -133,7 +133,7 @@ bash ./restart.sh
 项目共有如下3个的文档，以便查看了解
 
 - [README](./README.md) ：项目本身的文档，快速了解项目
-- [HOWTOCODE](./HOWTOCODE.md) ：更深的了解项目，包括架构设计、执行原理、应用配置、单元测试等
+- [HOWTOCODE](./HOWTOCODE.md) ：更深的了解项目，包括架构设计、底层原理、应用配置、单元测试等
 - [HELP](./HELP.md) ：解决安装和部署过程中问题的帮助手册，包括镜像制作帮助、容器部署帮助等
 
 ### <span id="52">2、参与项目</span>

diff --git a/app/alpha/user/UserHandler.php b/app/alpha/user/UserHandler.php
@@ -12,18 +12,39 @@
 
 class UserHandler
 {
+    /**
+     * The event callback on database insert.
+     *
+     * @param array $parsedCanalData
+     *
+     * @return bool
+     */
     public function onInsert(array $parsedCanalData): bool
     {
-        return (new UserService())->handleInsert($parsedCanalData);
+        return (new UserService())->doInsert($parsedCanalData);
     }
 
+    /**
+     * The event callback on database update.
+     *
+     * @param array $parsedCanalData
+     *
+     * @return bool
+     */
     public function onUpdate(array $parsedCanalData): bool
     {
-        return (new UserService())->handleUpdate($parsedCanalData);
+        return (new UserService())->doUpdate($parsedCanalData);
     }
 
+    /**
+     * The event callback on database delete.
+     *
+     * @param array $parsedCanalData
+     *
+     * @return bool
+     */
     public function onDelete(array $parsedCanalData): bool
     {
-        return (new UserService())->handleDelete($parsedCanalData);
+        return (new UserService())->doDelete($parsedCanalData);
     }
 }
diff --git a/app/alpha/user/UserService.php b/app/alpha/user/UserService.php
@@ -12,26 +12,54 @@
 
 class UserService
 {
+    /**
+     * Get userid of user.
+     *
+     * @param int $userid
+     *
+     * @return int
+     */
     public function getUserId(int $userid): int
     {
         return ($userid * 100) + 5;
     }
 
-    public function handleInsert(array $parsedCanalData): bool
+    /**
+     * Do insert business things.
+     *
+     * @param array $parsedCanalData
+     *
+     * @return bool
+     */
+    public function doInsert(array $parsedCanalData): bool
     {
-        Logger::logInfo("result(UserService -> handleInsert) : success");
+        Logger::logInfo("result(UserService -> doInsert) : success");
         return true;
     }
 
-    public function handleUpdate(array $parsedCanalData): bool
+    /**
+     * Do update business things.
+     *
+     * @param array $parsedCanalData
+     *
+     * @return bool
+     */
+    public function doUpdate(array $parsedCanalData): bool
     {
-        Logger::logInfo("result(UserService -> handleUpdate) : success");
+        Logger::logInfo("result(UserService -> doUpdate) : success");
         return true;
     }
 
-    public function handleDelete(array $parsedCanalData): bool
+    /**
+     * Do delete business things.
+     *
+     * @param array $parsedCanalData
+     *
+     * @return bool
+     */
+    public function doDelete(array $parsedCanalData): bool
     {
-        Logger::logInfo("result(UserService -> handleDelete) : success");
+        Logger::logInfo("result(UserService -> doDelete) : success");
         return true;
     }
 }
diff --git a/app/common/DBService.php b/app/common/DBService.php
@@ -10,16 +10,67 @@
 
 class DBService
 {
+
+    /**
+     * The host for accessing database.
+     *
+     * @var string
+     */
     private $host;
+
+    /**
+     * The port for accessing database.
+     *
+     * @var string
+     */
     private $port;
+
+    /**
+     * The account name for accessing database.
+     *
+     * @var string
+     */
     private $username;
+
+    /**
+     * The password for accessing database.
+     *
+     * @var string
+     */
     private $password;
+
+    /**
+     * The database name for accessing database.
+     *
+     * @var string
+     */
     private $database;
+
+    /**
+     * The charset for accessing database.
+     *
+     * @var string
+     */
     private $charset;
 
+    /**
+     * The mysqli instance.
+     *
+     * @var \mysqli
+     */
     private $mysqliObject;
 
-    public function __construct($host, $port, $username, $password, $database, $charset)
+    /**
+     * Constructs a database service.
+     *
+     * @param string $host
+     * @param string $port
+     * @param string $username
+     * @param string $password
+     * @param string $database
+     * @param string $charset
+     */
+    public function __construct(string $host, string $port, string $username, string $password, string $database, string $charset)
     {
         $this->host         = $host;
         $this->port         = $port;

diff --git a/app/common/ESService.php b/app/common/ESService.php
@@ -12,13 +12,44 @@
 
 class ESService
 {
+    /**
+     * The host for accessing elasticsearch.
+     *
+     * @var string
+     */
     public $host;
+
+    /**
+     * The port for accessing elasticsearch.
+     *
+     * @var string
+     */
     public $port;
+
+    /**
+     * The user:password for accessing elasticsearch.
+     *
+     * @var string
+     */
     public $userPassword;
+
+    /**
+     * The field of _type for accessing elasticsearch.
+     *
+     * @var string
+     */
     public $documentType;
 
+    /**
+     * The index for accessing elasticsearch.
+     *
+     * @var string
+     */
     public $index;
 
+    /**
+     * The different curl method.
+     */
     const METHOD_GET = 'GET';
     const METHOD_POST = 'POST';
     const METHOD_PUT = 'PUT';
@@ -35,12 +66,32 @@ public function __construct($index)
         $this->index = $index;
     }
 
+    /**
+     * Is the changed filed need to update elasticsearch.
+     *
+     * @param array $changedFieldList
+     *
+     * @param array $needToUpdateFieldList
+     *
+     * @return bool
+     */
     public function isNeedToUpdate(array $changedFieldList, array $needToUpdateFieldList): bool
     {
         $result = array_intersect($changedFieldList, $needToUpdateFieldList);
         return !empty($result);
     }
 
+    /**
+     * Update a document.
+     *
+     * @param $documentId
+     *
+     * @param $updateList
+     *
+     * @param false $upsert
+     *
+     * @return bool
+     */
     public function updateDoc($documentId, $updateList, $upsert = false): bool
     {
         $url     = "{$this->host}:{$this->port}/{$this->index}/{$this->documentType}/{$documentId}/_update";
@@ -61,6 +112,15 @@ public function updateDoc($documentId, $updateList, $upsert = false): bool
         return $this->curlRequest($url, self::METHOD_POST, $data);
     }
 
+    /**
+     * Put a document.
+     *
+     * @param $documentId
+     *
+     * @param $document
+     *
+     * @return bool
+     */
     public function putDoc($documentId, $document): bool
     {
         $url     = "{$this->host}:{$this->port}/{$this->index}/{$this->documentType}/{$documentId}";
@@ -75,11 +135,29 @@ public function putDoc($documentId, $document): bool
         return $this->curlRequest($url, self::METHOD_PUT, $data);
     }
 
+    /**
+     * Is success or not.
+     *
+     * @param int $httpCode
+     *
+     * @return bool
+     */
     public function isSuccess(int $httpCode): bool
     {
         return intval($httpCode) >= 200 && intval($httpCode) < 300;
     }
 
+    /**
+     * Request the elasticsearch by http.
+     *
+     * @param string $url
+     *
+     * @param string $method
+     *
+     * @param string $data
+     *
+     * @return bool
+     */
     public function curlRequest(string $url, string $method, string $data): bool
     {
         $ch = curl_init();