diff --git a/blog/Start-SourceCode-Analysis-Start-Demo-for-Contributor.md b/blog/Start-SourceCode-Analysis-Start-Demo-for-Contributor.md new file mode 100644 index 00000000000..05d4e7eb2da --- /dev/null +++ b/blog/Start-SourceCode-Analysis-Start-Demo-for-Contributor.md @@ -0,0 +1,206 @@ +--- +title: Guide for New Contributors to Start avoid Pitfalls +author: Yuxuan Zhang +author_title: Apache ShenYu Contributor +author_url: https://github.com/zuobiao-zhou +author_image_url: https://avatars.githubusercontent.com/u/61108539?s=400&u=f065b78a2944f2cea9160de7f7df054e2f157867&v=4 +tags: [first-start,Apache ShenYu] +--- + +## Preface + +As a first-time developer in the `Shenyu` community, I encountered some "Pitfalls" that were not mentioned in the tutorials I followed to start and develop the project. I have documented the detailed steps I took to start `shenyu`, `shenyu-dashboard`, `shenyu-website` in this blog, hoping to help more new contributors in the community. + +## Environmental Preparation + +- Correct local installation of `JDK1.8+` +- Properly install `Git` locally +- Choose a development tool, this article uses `IDEA` as an example + +## ShenYu Backend Startup Guide + +### Install and Configure Maven + +Maven is a cross-platform project management tool . As the Apache organization's top open source projects , its main service for Java-based platform project creation , dependency management and project information management. + +1. [Download maven](https://maven.apache.org/download.cgi) and extract it to a path with no Chinese and no spaces. + + + +2. Add the `bin` directory under the `maven` directory to the environment variables. For `Windows`, if the download directory is `E:\apache-maven-3.9.1`, add `E:\apache-maven-3.9.1\bin` to the `Path` system variable. + +3. Verify that the installation was successful. Type `mvn -v` in the cmd window, and if the Maven version and Java version appear, the installation is successful. This is shown below: + + ```shell + C:\Users\pc>mvn -v + Apache Maven 3.9.1 (2e178502fcdbffc201671fb2537d0cb4b4cc58f8) + Maven home: E:\apache-maven-3.9.1 + Java version: 18.0.1.1, vendor: Oracle Corporation, runtime: C:\Program Files\Java\jdk-18.0.1.1 + Default locale: zh_CN, platform encoding: UTF-8 + OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows" + ``` + +4. To speed up the download of project-related dependencies, you need to change the Maven mirrors, here add Aliyun and other mirrors. Change the ` ` tag pair in `conf/settings.xml` to the following: + + ```xml + + + alimaven + aliyun maven + http://maven.aliyun.com/nexus/content/groups/public/ + central + + + + alimaven + central + aliyun maven + http://maven.aliyun.com/nexus/content/repositories/central/ + + + + maven + central + name_ + http://repo1.maven.org/maven2 + + + + junit + central + junit address/ + http://jcenter.bintray.com/ + + + ``` + + and add `E:/maven_local_repository` to the next line of `` to set the location of Maven local repository. You can specify the exact location yourself. + +### Pull ShenYu Code + +1. Fork [ShenYu](https://github.com/apache/shenyu) repository on Github to your own repository, where you can develop and commit PRs in the future +2. Use Git to download the repository from the previous step locally: + + ```shell + git clone git@github.com:${YOUR_USERNAME}/${TARGET_REPO}.git + ``` + + If prompted for a long file name, execute the following command via the command line: + + ```shell + git config --global core.longpaths true + ``` + +### ShenYu First Start + +#### Preparation + +1. Compile with Maven in the `shenyu` directory: + + ```shell + mvn clean install -Dmaven.javadoc.skip=true -B -Drat.skip=true -Djacoco.skip=true -DskipITs -DskipTests + ``` + +2. Configure IDEA environment. Open `shenyu` project with IDEA, click `File` -> `Settings` in the top left corner, and configure Maven as shown below. Where `User settings file` select your `settings.xml` directory, and then `Local repository` will automatically load the `localRepository` path set in `settings.xml`: + + + +3. At this point, IDEA will automatically download the project-related dependencies, you need to wait for a while, when finished, as shown in the following figure: + + + + As you can see, `shenyu-e2e`, `shenyu-examples`, `shenyu-integrated-test` are not marked as Maven projects by IDEA and need to be added manually. Select the `pom.xml` file in the package and right-click `Add as Maven Project`. + If the shenyu-e2e build fails, then add the `. /pom.xml` to ``. + +#### Start Gateway Service + +1. Start the `shenyu-admin` console (H2 database is used by default) + + + +2. start `shenyu-bootstrap` + + + +> By this point, the shenyu gateway has been started. +> +> We can open the browser and access the admin console: [http://localhost:9095/](http://localhost:9095/) +> +> Default account: admin , default password: 123456 + +#### Start Application Service + +Apache ShenYu provides samples of Http, Dubbo, SpringCloud and other applications to access the shenyu gateway, located in the `shenyu-example` module, here the `Http service` is used as an example. + +Start `shenyu-examples-http`。 + + + +At this point, `shenyu-examples-http` will automatically register the interface methods annotated with `@ShenyuSpringMvcClient` and the relevant configuration in application.yml to the gateway. We can open the [admin console](http://localhost:9095/) and see the configuration in `Client List -> Proxy -> divide`. + +#### Test Http Request + +The following uses the `IDEA HTTP Client Plugin` to mock http to access http services. +- Local access without using shenyu proxy + + + +- Use shenyu proxy + + + +### Use more plugins + +We can refer to the [official documentation](../docs/index) to the left of `Plugins collection` to use the required plugins. + +## Shenyu Front End Startup Guide + +### Install Node.js + +#### Download + +1. Download and install Node.js from [official website](https://nodejs.org/en) and select `LTS` version. +2. When installing, except for setting the installation path, just keep clicking `Next`. +3. After the installation is complete, verify at the command line: + + ```shell + C:\Users\pc>node -v + v12.22.12 + + C:\Users\pc>npm -v + 6.14.16 + ``` + +### Pull ShenYu Dashboard Code + +1. Fork [ShenYu Dashboard](https://github.com/apache/shenyu-dashboard) repository +2. Using Git to download locally + + ```shell + git clone git@github.com:${YOUR_USERNAME}/${TARGET_REPO}.git + ``` + +### Front and Back End Co-development + +1. Add `enablePrintApiLog: true` to the `shenyu-admin/src/main/resources/application.yml` file in the backend repository `shenyu` as shown below to show the log of frontend interface calls in the backend console. + + + +2. Start `ShenyuAdminBootstrap` + +3. Switch to the front-end repository `shenyu-dashboard`, open `README`, click `npm install`, `npm start` or enter the above command from cmd to access the front-end interface via [http://localhost:8000](http://localhost:8000), and display the log of the front-end interface called in the back-end console. Realize the co-development of front-end and back-end. + + + +### Package Front-end Code + +Execute the `npm build` command in `README` and copy all the generated files from the `dist` folder to the `shenyu-admin/src/main/resources/static/` directory in the backend repository. + +## Contribute to Shenyu Official Website + +Just follow the `README` in [shenyu-website](https://github.com/apache/shenyu-website). + +### Tips + +1. I recommend downloading the `LTS` version from the `Node` [website](https://nodejs.org/en). +2. `Windows` systems cannot be deployed, if you want to verify your changes, you can deploy on a Linux virtual machine or server. diff --git a/i18n/zh/code.json b/i18n/zh/code.json index da97d1aa635..98a7348c12f 100755 --- a/i18n/zh/code.json +++ b/i18n/zh/code.json @@ -334,6 +334,12 @@ "Apache ShenYu Start Demo": { "message": "Apache ShenYu 启动示例" }, + "Guide for New Contributors to Start avoid Pitfalls": { + "message": "Apache ShenYu 新人开发者启动及开发防踩坑指南" + }, + "As a first-time developer in the `Shenyu` community, I encountered some \"Pitfalls\" that were not mentioned in the tutorials I followed to start and develop the project. I have documented the detailed steps I took to start `shenyu`, `shenyu-dashboard`, `shenyu-website` in this blog, hoping to help more new contributors in the community.": { + "message": "作为 `Shenyu` 社区初来乍到的开发者,我在按照相关教程进行项目启动及开发的过程中,遇到了一些教程中并未提及到的 “坑” ,我将我启动`shenyu` , `shenyu-dashboard`, `shenyu-website` 的详细步骤记录在这篇博客中,希望可以帮到社区中更多的新人开发者。" + }, "Etcd Data Synchronization Source Code Analysis": { "message": "Etcd数据同步源码分析" }, diff --git a/i18n/zh/docusaurus-plugin-content-blog/Start-SourceCode-Analysis-Start-Demo-for-Contributor.md b/i18n/zh/docusaurus-plugin-content-blog/Start-SourceCode-Analysis-Start-Demo-for-Contributor.md new file mode 100644 index 00000000000..0a9cad9543f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-blog/Start-SourceCode-Analysis-Start-Demo-for-Contributor.md @@ -0,0 +1,220 @@ +--- +title: 社区新人开发者启动及开发防踩坑指南 +author: Yuxuan Zhang +author_title: Apache ShenYu Contributor +author_url: https://github.com/zuobiao-zhou +author_image_url: https://avatars.githubusercontent.com/u/61108539?s=400&u=f065b78a2944f2cea9160de7f7df054e2f157867&v=4 +tags: [first-start,Apache ShenYu] +--- + +## 前言 + +作为 `Shenyu` 社区初来乍到的开发者,我在按照相关教程进行项目启动及开发的过程中,遇到了一些教程中并未提及到的 “坑” , 我将我启动`shenyu` , `shenyu-dashboard`, `shenyu-website` 的详细步骤记录在这篇博客中,希望可以帮到社区中更多的新人开发者。 + +## 环境准备 + +- 本地正确安装 `JDK1.8+` +- 本地正确安装 `Git` +- 选择一款开发工具,本文使用 `IDEA` 为例 + +## ShenYu 后端启动指南 + +### 安装并配置Maven + +Maven是一个跨平台的项目管理工具。作为Apache组织顶级开源项目,其主要服务于基于Java平台的项目创建,依赖管理和项目信息管理。 + +1. [下载 maven](https://maven.apache.org/download.cgi),并解压到一个没有中文没有空格的路径下。 + + ![](/img/activities/start-demo-for-contributor/maven-install.png) + +2. 将 `maven` 目录下的 `bin` 目录添加至环境变量中。以 `Windows` 为例,若下载目录为 `E:\apache-maven-3.9.1` ,则将`E:\apache-maven-3.9.1\bin` 添加至 `Path` 系统变量中。 + +3. 验证是否安装成功。在命令行窗口中输入 `mvn -v` ,若出现 Maven 版本及 Java 版本即为安装成功。如下所示: + + ```shell + C:\Users\pc>mvn -v + Apache Maven 3.9.1 (2e178502fcdbffc201671fb2537d0cb4b4cc58f8) + Maven home: E:\apache-maven-3.9.1 + Java version: 18.0.1.1, vendor: Oracle Corporation, runtime: C:\Program Files\Java\jdk-18.0.1.1 + Default locale: zh_CN, platform encoding: UTF-8 + OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows" + ``` + +4. 为了加快项目相关依赖的下载速度,需要更改 Maven 镜像,此处添加阿里云等镜像。将 `conf/settings.xml` 中 ` ` 标签对更改为以下内容: + + ```xml + + + alimaven + aliyun maven + http://maven.aliyun.com/nexus/content/groups/public/ + central + + + + alimaven + central + aliyun maven + http://maven.aliyun.com/nexus/content/repositories/central/ + + + + maven + central + name_ + http://repo1.maven.org/maven2 + + + + junit + central + junit address/ + http://jcenter.bintray.com/ + + + ``` + + 并在 `` 下一行添加 `E:/maven_local_repository`设置 Maven 本地仓库位置。具体位置可自行指定。 + +### 拉取 ShenYu 代码 + +1. 在 Github 上 Fork [ShenYu](https://github.com/apache/shenyu) 仓库到自己的存储库中,以后可在此仓库中进行开发并提交 PR +2. 使用 Git 将上一步 Fork 的仓库下载到本地: + + ```shell + git clone git@github.com:${YOUR_USERNAME}/${TARGET_REPO}.git + ``` + + 若提示文件名过长,则通过命令行执行下面的命令: + + ```shell + git config --global core.longpaths true + ``` + +### ShenYu 初启动 + +#### 准备工作 + +1. 在 `shenyu` 目录下使用 Maven 进行编译: + + ```shell + mvn clean install -Dmaven.javadoc.skip=true -B -Drat.skip=true -Djacoco.skip=true -DskipITs -DskipTests + ``` + +2. 配置 IDEA 环境。使用 IDEA 打开 `shenyu` 项目,点击左上角 `File` -> `Settings` ,按照下图配置 Maven 。其中 `User settings file` 选择你的 `settings.xml` 所在目录, `Local repository` 会自动加载 `settings.xml` 中设置的 `localRepository` 路径: + + ![](/img/activities/start-demo-for-contributor/idea-config.png) + +3. 此时,IDEA 会自动下载项目相关依赖,需等待一会,完成后如下图所示: + + ![](/img/activities/start-demo-for-contributor/project-without-example.png) + + 可以发现, `shenyu-e2e`, `shenyu-examples`, `shenyu-integrated-test` 没有被 IDEA 标记为 Maven 项目,需手动添加。分别选中包中的 `pom.xml` 文件,右键点击 `Add as Maven Project` 。 + 若 shenyu-e2e 构建失败,则将其 `pom.xml` 中 `./pom.xml` 改为 `` 。 + +#### 启动网关服务 + +1. 启动 `shenyu-admin` 控制台(默认使用H2数据库) + + ![](/img/activities/start-demo-for-contributor/admin.png) + +2. 启动 `shenyu-bootstrap` + + ![](/img/activities/start-demo-for-contributor/bootstrap.png) + +> 到这一步,shenyu网关已经启动。 +> +> 我们可以打开浏览器,访问admin控制台:[http://localhost:9095/](http://localhost:9095/) +> +> 默认账号:admin ,默认密码:123456 + +#### 启动应用服务 + +Apache ShenYu提供了Http、Dubbo、SpringCloud等应用接入shenyu网关的样例,位于 `shenyu-example` 模块,这里以Http服务为例。 + +启动 `shenyu-examples-http`。 + +![](/img/activities/start-demo-for-contributor/shenyu-examples-http.png) + +这时,`shenyu-examples-http` 会自动把加 `@ShenyuSpringMvcClient` 注解的接口方法,以及application.yml中的相关配置注册到网关。我们打开 [admin控制台](http://localhost:9095/),即可在`插件列表 -> Proxy -> divide` 中看到相关配置。 + +#### 测试Http请求 + +下面使用 `IDEA HTTP Client Plugin` 模拟 http 的方式来访问 http 服务。 +- 本地访问,不使用 shenyu 代理 + + ![](/img/activities/start-demo-for-contributor/shenyu-http-test-api-local.png) + +- 使用 shenyu 代理 + + ![](/img/activities/start-demo-for-contributor/shenyu-http-test-api.png) + +### 使用更多插件 + +我们可以参考 [官方文档](../docs/index)左侧`插件集合`,来使用所需要插件。 + +## Shenyu 前端启动指南 + +### 安装 Node.js + +#### 下载 + +1. 在[官网](https://nodejs.org/en)下载并安装Node.js ,选择 `LTS` 版本即可 +2. 安装时,除了设置安装路径,其他一直点 `Next` 即可 +3. 安装完成后,在命令行中进行验证: + + ```shell + C:\Users\pc>node -v + v12.22.12 + + C:\Users\pc>npm -v + 6.14.16 + ``` + +#### 换源 + +为了加快 npm 下载速度,需要进行换源: + +```shell +# 查看当前源 +npm config get registry +# 换为中国 npmmirror 镜像源 +npm config set registry https://registry.npmmirror.com +# 查看是否换源成功 +npm config get registry +``` + +### 拉取 ShenYu Dashboard 代码 + +1. Fork [ShenYu Dashboard](https://github.com/apache/shenyu-dashboard) 仓库 +2. 使用 Git 下载到本地: + + ```shell + git clone git@github.com:${YOUR_USERNAME}/${TARGET_REPO}.git + ``` + +### 前后端联合开发 + +1. 在后端仓库 `shenyu` 的 `shenyu-admin/src/main/resources/application.yml` 文件中按下图所示添加 `enablePrintApiLog: true` ,以在后端控制台显示前端接口被调用的日志。 + + ![](/img/activities/start-demo-for-contributor/enable-api-log.png) + +2. 启动 `ShenyuAdminBootstrap` + +3. 切换至前端仓库 `shenyu-dashboard` ,打开 `README` ,依次点击 `npm install`, `npm start` 或通过命令行输入上述命令即可通过 [http://localhost:8000](http://localhost:8000) 访问前端界面,并可在后端控制台中显示前端接口被调用的日志,实现前后端联合开发。 + + ![](/img/activities/start-demo-for-contributor/admin-log.png) + +### 打包前端代码 + +执行 `README` 中 `npm build` 命令,并将 dist 文件夹下生成的所有文件复制到后端仓库中 `shenyu-admin/src/main/resources/static/` 目录下。 + +## 为 Shenyu 官网做贡献 + +按照 [shenyu-website](https://github.com/apache/shenyu-website) 中 `README` 进行操作即可。 + +### 小贴士 + +1. 可以为 `yarn` 进行换源,流程同 `npm` +2. 建议下载 `Node` [官网](https://nodejs.org/en)中 `LTS` 版本 +3. `Windows` 系统无法进行部署,如需对你的更改进行验证,可以在Linux 虚拟机或服务器上进行部署 diff --git a/src/data/blogInfo.js b/src/data/blogInfo.js index e89737a5172..f021d0de5e3 100644 --- a/src/data/blogInfo.js +++ b/src/data/blogInfo.js @@ -86,6 +86,16 @@ export default [ date: '2021-07-2', abs:Apache ShenYu Start Demo }, + { + title: Guide for New Contributors to Start avoid Pitfalls, + author: "Yuxuan Zhang (Contributor)", + autImg: "/img/blog/zhangyuxuan.png", + autPage:"https://github.com/zuobiao-zhou", + src: "Start-SourceCode-Analysis-Start-Demo-for-Contributor", + cover: "/img/blog/7-1.png", + date: '2023-04-18', + abs:As a first-time developer in the `Shenyu` community, I encountered some "Pitfalls" that were not mentioned in the tutorials I followed to start and develop the project. I have documented the detailed steps I took to start `shenyu`, `shenyu-dashboard`, `shenyu-website` in this blog, hoping to help more new contributors in the community. + }, ] }, { diff --git a/static/img/activities/start-demo-for-contributor/admin-log.png b/static/img/activities/start-demo-for-contributor/admin-log.png new file mode 100644 index 00000000000..d54280fd106 Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/admin-log.png differ diff --git a/static/img/activities/start-demo-for-contributor/admin.png b/static/img/activities/start-demo-for-contributor/admin.png new file mode 100644 index 00000000000..5999146a862 Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/admin.png differ diff --git a/static/img/activities/start-demo-for-contributor/bootstrap.png b/static/img/activities/start-demo-for-contributor/bootstrap.png new file mode 100644 index 00000000000..89868e38f28 Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/bootstrap.png differ diff --git a/static/img/activities/start-demo-for-contributor/enable-api-log.png b/static/img/activities/start-demo-for-contributor/enable-api-log.png new file mode 100644 index 00000000000..9f15fd9f337 Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/enable-api-log.png differ diff --git a/static/img/activities/start-demo-for-contributor/idea-config.png b/static/img/activities/start-demo-for-contributor/idea-config.png new file mode 100644 index 00000000000..9541431372e Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/idea-config.png differ diff --git a/static/img/activities/start-demo-for-contributor/maven-install.png b/static/img/activities/start-demo-for-contributor/maven-install.png new file mode 100644 index 00000000000..c5ac4148f47 Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/maven-install.png differ diff --git a/static/img/activities/start-demo-for-contributor/project-without-example.png b/static/img/activities/start-demo-for-contributor/project-without-example.png new file mode 100644 index 00000000000..77cf188927f Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/project-without-example.png differ diff --git a/static/img/activities/start-demo-for-contributor/shenyu-examples-http.png b/static/img/activities/start-demo-for-contributor/shenyu-examples-http.png new file mode 100644 index 00000000000..f3f29ba9e16 Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/shenyu-examples-http.png differ diff --git a/static/img/activities/start-demo-for-contributor/shenyu-http-test-api-local.png b/static/img/activities/start-demo-for-contributor/shenyu-http-test-api-local.png new file mode 100644 index 00000000000..4c2c8db6730 Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/shenyu-http-test-api-local.png differ diff --git a/static/img/activities/start-demo-for-contributor/shenyu-http-test-api.png b/static/img/activities/start-demo-for-contributor/shenyu-http-test-api.png new file mode 100644 index 00000000000..cc7dc980df1 Binary files /dev/null and b/static/img/activities/start-demo-for-contributor/shenyu-http-test-api.png differ diff --git a/static/img/blog/7-1.png b/static/img/blog/7-1.png new file mode 100644 index 00000000000..5999146a862 Binary files /dev/null and b/static/img/blog/7-1.png differ diff --git a/static/img/blog/zhangyuxuan.png b/static/img/blog/zhangyuxuan.png new file mode 100644 index 00000000000..8f85dcb4c8f Binary files /dev/null and b/static/img/blog/zhangyuxuan.png differ