Design a web architecture based on React18+Mobx

[mominger]

Project architecture diagram

Technology stack of project

The upper part is the English version, and the lower part is the Chinese version, with the same content. If there are any wrong, or you have anything hard to understand, pls feel free to let me know.many thx.

Based on React 18, React Route 6.x, Mobx 6.x Project address

• Project architecture diagram
• Technology stack of project
• 1. Key design
  • 1.1 Business decoupling
  • 1.2 Views compatible for Mobile and PC
  • 1.3 Authentication
  • 1.4 I18n
  • 1.5 Directory Structure
• 2. Network request and service processing
  • 2.1 Flow
  • 2.2 code of View Layer
  • 2.3 code example of page store
  • 2.4 http.ts code
• 3. Utils
  • 3.1 Content
  • 3.2 Internationalization
  • 3.3 Contants
  • 3.4 Config
• 4. Page Container
  • 4.1 components
  • 4.1.1 Page root component
  • 4.2 Router
  • 4.2.1 Register Routes
  • 4.2.3 Define Route for certain page module
  • 4.3 MobX state management
  • 4.3.1 Define store
  • 4.3.2 Store used in page
• 5. UI component library
  • 5.1 integrate Antd
• 6. Compile and package
  • 6.1 Configuration items
  • 6.2 Debugger by mock environment
  • 6.2.1 Add mock data
  • 6.2.2 Exec yarn mock
  • 6.3.3 Principle analysis
• 7. Log
  • 7.1 Catching React Exceptions
  • 7.2 Log upload
• 8. Unit Test
  • 8.1 add unit test
  • 8.2 Check out coverage
• 9. Pre Commit
  • 9.1 Code format
  • 9.2 Validate commit message
• 10 Compatible for Mobile and PC
  • 10.1 Load the corresponding global style
  • 10.2 Load the corresponding hooks/components inside the page
  • 10.3 Load the corresponding page component inside the router
  • 10.4 Example
• 11. Other

1. Key design

1.1 Business decoupling

When R&D developers are working at the same time, and the business is complex, it is necessary to divide the business into modules and decouple it Such as there are A, B, C, etc modules, they will be isolated at key layers such as Store, Api, Page etc.

1.2 Views compatible for Mobile and PC

There are about 3 ways for views to be compatible with mobile and PC.

• Different projects: When the user enters the URL in the browser, response the corresponding mobie or pc page by nginx parsed useAgent
• Different page components: When the user enters the URL in the browser, it is determined by the userAgent, if the mobile or pc page component is mounted on the routing path.
• The same page component: determine the rendering of mobile or pc pages through parsing userAgent inside the page component

  Of course, it can also be determined according to the browser resolution, or browser resolution + userAgent. In our project I choose is the 'different page components' method, you can check out the details on 10 Compatible for Mobile and PC

1.3 Authentication

Set isAuth for each route in every routes.ts. The default isAuth is true, which means authentication is required If authentication is required, It will render login component first unless it has logged in.

pls refer to require-auth component

1.4 I18n

There are 2 ways to process I18n for project as follows

• Support to write internationalized code anywhere, including any js file, and then switch the language by window.location.reload()
• Only supports writing internationalized code in React components, and switchs language by hooks

  Since the second one does not need to reload pages, more friendly experience, so use it in this project pls refer to demo page component

1.5 Directory Structure

The following is an explanation of each layer of the architecture Postman/Swagger in bottom of architecture means after providing API documents in the back-end, use them for debugging

2. Network request and service processing

2.1

2.2 code of View Layer

Store.onLoad(action) is automatically called through the page root component Page Or the page calls the api through store.action Refer to pages/home/index.tsx for details

2.3 code example of page store

If the page is wrapped by components/page component, onLoad in Store will be executed automatically when the page is initialized, execute automatically onUnload in Store when the page is unloaded.

Define a methed for calling api

call api in store

All interface type are defined in @types directory Refer to store/home' for more detail

2.4 http.ts code

Refer to http/base/http for more detail MobX builds store, which is equivalent to the page model layer, and the model layer is responsible for calling the Apis Compared with the Redux (dispatch(action) -> reducer -> new state) process, the store class of MobX looks natural and simple; in addition, Redux needs to rely on middleware, such as the plug-in Redux-thunk to call Api, but MobX does not. Finally, the Redux update component needs to be obtained asynchronously through store.subscribe, and MobX is a synchronous and responsive update. The above is the reason for replacing Redux with MobX.

3. Utils

There are many auxiliary JS classes under the helper package

3.1 Content

3.2 Internationalization

3.3 Contants

3.4 Config

Generate configuration items based on env in different environments

For others, please check the code under helper

4. Page Container

All pages are placed under pages, and public components are placed under components

4.1 components

If it is not a public component, only used for a certain page, pls placed in the components folder of the corresponding page. such as home/components

4.1.1 Page root component

Extracting the root component is to reuse some common logic of all pages. For example, it will automatically process the initialization onLoad and unload onUnload of all page stores. For others, please check the code under components

4.2 Router

use React Router 6.x

4.2.1 Register Routes

4.2.3 Define Route for certain page module

Chunk name will display when loading

4.3 MobX state management

4.3.1 Define store

Init every store

All store wrapped in Context

Responsive variables, initialize action onLoad, unload action onUnload, other actions, computed variables

4.3.2 Store used in page

Call action/variables through store.xxx Example code is in pages/home

5. UI component library

For some common ui libraries such as Bootstrap, Material UI, Andt, etc, are easy to integrate into the project. The following is an example of integrating Antd.

5.1 integrate Antd

6. Compile and package

6.1 Configuration items

Can override webpack configuration information Refer to configuration item description

6.2 Debugger by mock environment

6.2.1 Add mock data

add mock data for certain api in mocks directory

6.2.2 Exec yarn mock

6.3.3 Principle analysis

Launch a mock server by koa

Set BASEURL to mock server host in .env.mock, so all request will connect to it

7. Log

7.1 Catching React Exceptions

7.2 Log upload

At present, after the exception logs are collected in helper/log, they are only printed to the console, and normally should be uploaded to the log platform, such as Sentry. Note: Asynchronous exceptions such as Promises need to be caught by try...catch

8. Unit Test

8.1 add unit test

add unit test file in __tests__/unit directory use assert of jest for common function, such as js-dom-test-spec.js use enzyme or testing-library for react component, such as app-spec.js exec command yarn test Refer to Jest 27.x create-react-app unit test enzyme

8.2 Check out coverage

exec command yarn test:coverage

9. Pre Commit

9.1 Code format

9.2 Validate commit message

validate commit msg by commitlint, Refer to commitlint Message format such as 'feat: AAX-XXX...'

10 Compatible for Mobile and PC

10.1 Load the corresponding global style

10.2 Load the corresponding hooks/components inside the page

10.3 Load the corresponding page component inside the router

If in mobile envorinment, mount the mobile page component , otherwise, mount the pc page component

10.4 Example

mobile

pc

11. Other

• The helper/hooks folder shows 1 hook examples
• It is recommended to use memo+useMemo+useCallback for components to avoid repeated rendering

The following is the Chinese version, the same content as above

架构图

技术栈

基于 React 18, React Route 6.x, Mobx 6.x 源码地址

• 架构图
• 技术栈
• 1. Key design
  • 1.1 Business decoupling
  • 1.2 Views compatible for Mobile and PC
  • 1.3 Authentication
  • 1.4 I18n
  • 1.5 Directory Structure
• 2.Network request and service processing
  • 2.1 Flow
  • 2.2 code of View Layer
  • 2.3 code example of page store
  • 2.4 http.ts code
• 3. Utils
  • 3.1 Content
  • 3.2 Internationalization
  • 3.3 Contants
  • 3.4 Config
• 4. Page Container
  • 4.1 components
  • 4.1.1 Page root component
  • 4.2 Router
  • 4.2.1 Register Routes
  • 4.2.3 Define Route for certain page module
  • 4.3 MobX state management
  • 4.3.1 Define store
  • 4.3.2 Store used in page
• 5. UI component library
  • 5.1 integrate Antd
• 6. Compile and package
  • 6.1 Configuration items
  • 6.2 Debugger by mock environment
  • 6.2.1 Add mock data
  • 6.2.2 Exec yarn mock
  • 6.3.3 Principle analysis
• 7. Log
  • 7.1 Catching React Exceptions
  • 7.2 Log upload
• 8. Unit Test
  • 8.1 add unit test
  • 8.2 Check out coverage
• 9. Pre Commit
  • 9.1 Code format
  • 9.2 Validate commit message
• 10 Compatible for Mobile and PC
  • 10.1 Load the corresponding global style
  • 10.2 Load the corresponding hooks/components inside the page
  • 10.3 Load the corresponding page component inside the router
  • 10.4 Example
• 11. Other

1. Key design

1.1 Business decoupling

当研发人员同时工作，业务复杂时，需要将业务划分为模块，解耦 比如有A、B、C等模块，会在Store、Api、Page等关键层进行隔离。

1.2 Views compatible for Mobile and PC

有如下 3 种方式可以让View层与Mobile和 PC端兼容。

• 不同项目：当用户在浏览器中输入URL时，通过nginx解析useAgent响应对应的mobie或pc页面
• 不同页面组件：当用户在浏览器中输入URL时，由userAgent判断，在路由上挂载mobile或pc页面组件。
• 页面组件内：通过在页面组件内部的userAgent来判断，渲染mobile或pc组件

  当然也可以根据浏览器分辨率来判定，或浏览器分辨率+userAgent。 在本项目中我采用的是'不同页面组件'的方法，具体可以查看10 Compatible for Mobile and PC的详细信息

1.3 Authentication

每个routes.ts里给每个路由设置isAuth.默认isAuth为true,代表需要鉴权 如果需要鉴权，则会判定是否已登录。没登录渲染login组件。已登录则正常渲染。 具体参考require-auth组件

1.4 I18n

有如下2种处理项目I18n的方式

• 支持在任何地方，包括任何js文件写国际化代码，然后通过window.location.reload() 来进行语言的切换
• 仅支持在react组件里写国际化代码，通过hook来进行语言的切换

  由于第二种不需要切换页面，体验更加友好，所以在本项目采用了它 具体参考demo 页面组件

1.5 Directory Structure

下面是架构图各层的解释 架构图底端的 Postman/Swagger 是指后端提供 API 文档后，用它们来调试

2.Network request and service processing

2.1 Flow

2.2 code of View Layer

Store.onLoad(action) 通过页面根组件Page自动调用 或页面通过store.action调用api 详见 pages/home/index.tsx

2.3 code example of page store

如果页面被components/page组件包裹，则页面初始化时会自动执行Store中的onLoad，卸载页面时会自动执行Store中的onUnload。

定义调用api的action

在 store 中调用 api

所有接口类型都定义在@types 里 详情请参阅store/home

2.4 http.ts code

更多详情请参考http/base/http MobX构建store，相当于model层，model层负责调用Api 相比于 Redux（dispatch(action) -> reducer -> new state）流程，MobX 的 store 类看起来自然简洁； 另外，Redux 需要依赖中间件，比如插件 Redux-thunk 调用 Api，而 MobX 不需要。 最后，需通过 store.subscribe 异步获取 Redux 更新组件，而 MobX 是同步响应式更新。 以上就是用 MobX 代替 Redux 的原因。

3. Utils

helper包下有很多辅助JS类

3.1 Content

3.2 Internationalization

3.3 Contants

3.4 Config

基于不同环境下的env生成配置项

更多详情请查看 helper 下的代码

4. Page Container

所有页面组件都放在pages下，公共组件放在components下

4.1 components

如果不是公共组件，只用于某个页面，请放在对应页面的 components 文件夹中。 例如 home/components

4.1.1 Page root component

提取根组件是为了重用页面的一些通用逻辑。 例如，它会自动处理所有页面store的初始化action: onLoad, onUnload。 其他请查看components的代码

4.2 Router

使用 React Router 6.x

4.2.1 Register Routes

4.2.3 Define Route for certain page module

加载时显示Chunk 名称

4.3 MobX state management

4.3.1 Define store

初始化每个store

所有store包裹在Context里

响应式变量，初始化action: onLoad，卸载action：onUnload，其他action，computed变量

4.3.2 Store used in page

通过store.xxx调用action/变量 示例代码在 pages/home

5. UI component library

对于一些常用的ui库如Bootstrap、Material UI、Andt 等，很容易集成到项目中。 下面是一个集成Antd的例子。

5.1 integrate Antd

6. Compile and package

6.1 Configuration items

可以覆盖webpack配置信息 Refer to configuration item description

6.2 Debugger by mock environment

6.2.1 Add mock data

在 mocks 目录中为一些 api 添加mock数据

6.2.2 Exec yarn mock

6.3.3 Principle analysis

通过koa启一个mock服务器

将 BASEURL 设置为 .env.mock 中的模拟服务器host，于是所有请求都会访问它

7. Log

7.1 Catching React Exceptions

7.2 Log upload

目前在helper/log中收集异常日志后，只打印到控制台，一般应该上传到日志平台，如Sentry。 注意：Promise 等异步异常需要通过 try...catch 来捕获

8. Unit Test

8.1 add unit test

在 __tests__/unit 目录中添加单元测试文件 jest 的 assert 可用于普通函数，在 js-dom-test-spec.js有示例代码 用 enzyme 或 testing-library 来测试react 组件，在 app-spec.js 有示例代码 执行命令yarn test 参考 Jest 27.x create-react-app unit test enzyme

8.2 Check out coverage

执行命令 yarn test:coverage

9. Pre Commit

9.1 Code format

9.2 Validate commit message

通过 commitlint 验证 commit msg，参考 commitlint msg格式如'feat: XXX...'

10 Compatible for Mobile and PC

10.1 Load the corresponding global style

10.2 Load the corresponding hooks/components inside the page

10.3 Load the corresponding page component inside the router

如果是mobile环境，挂载mobile端页面组件，否则，挂载pc端页面组件

10.4 Example

mobile

pc

11. Other

• helper/hooks 文件夹显示了 1 个hook示例
• 组件推荐使用memo+useMemo+useCallback，避免重复渲染

[mominger]

update key design