开发指引 on Macula

开发环境准备

Mon, 01 Jan 0001 00:00:00 +0000

前端环境准备

● Node.js 18.0及以上版本

● Visual Studio Code 1.72及以上版本

根据操作系统下载对应版本即可。

后端环境准备

● 相关工具

○ Git

○ JDK 1.8.0 及以上

○ maven 3.3 及以上

○ IDE(IDEA或Eclipse)

○ MySQL

○ Redis

○ Nacos

注：以下与window安装为例

● git安装

○ git window64位下载地址

双击Git-2.42.0.2-64-bit.exe直接安装即可

● JDK8安装

○ jdk8 官方下载地址

双击jdk-8u202-windows-x64.exe直接安装即可

● maven安装

○ maven 官方下载地址

解压apache-maven-3.9.5-bin.zip，将maven的bin目录加入到环境变量如下图

● IDEA安装

○ IDEA官方下载地址

双击ideaIU-2023.2.4.exe直接安装即可

● MySQL安装

○ mysql8 官方下载地址

部署Macula平台

Mon, 01 Jan 0001 00:00:00 +0000

(1) github代码clone

## 后端代码
git clone https://github.com/macula-projects/macula-cloud.git	
## 前端代码
git clone https://github.com/macula-projects/macula-cloud-admin.git

(2) 本地代码配置修改

（Macula平台本地运行需要修改的配置，都需要明确标注说明，如数据库【包括DDL初始化】、缓存、注册中心、配置中心、消息队列、网关地址、认证中心地址等【文字+截图】）

前端项目

修改 .env.development 文件为如下配置（根据实际情况调整）

VITE_APP_PROXY = false
VITE_APP_TITLE = macula-samples(local)
VITE_APP_API_BASEURL = http://localhost:9000 # gateway 地址
VITE_APP_IAM_URL=http://localhost:9010 # IAM 地址

后端项目

只有macula-cloud-iam、macula-cloud-system和macula-cloud-gateway是必须的。

初始化数据库脚本/macula-cloud/blob/main/macula-cloud-system/docs/macula-system-dump.sql

修改macula-cloud-iam 项目bootstrap.yml配置

server:
 port: 9010

spring:
 profiles:
 active: dev ## 指定程序以dev环境启动
application:
 name: macula-cloud-iam
cloud:
 nacos:
 username: ${nacos.username}
 password: ${nacos.password}
 config:
 server-addr: ${nacos.config.server-addr}
 namespace: ${nacos.config.namespace}
 # group:
 refresh-enabled: true
 file-extension: yml

---
spring:
 config:
 activate:
 on-profile: dev
nacos:
 username: ## dev环境的nacos用户名
 password: ## dev环境的nacos密码
 config:
 server-addr: ## dev环境的nacos服务地址
 namespace: ## dev环境的nacos命名空间

修改macula-cloud-iam 项目application.yml配置

spring:
 datasource:
 type: com.alibaba.druid.pool.DruidDataSource
 driver-class-name: com.mysql.cj.jdbc.Driver
 url: jdbc:mysql://127.0.0.1:3306/macula-system?zeroDateTimeBehavior=convertToNull&useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&autoReconnect=true ## mysql数据库地址及数据库名
 username: ## mysql数据库用户名
 password: ## mysql数据库密码
 redis:
 database: 0
 host: ## redis服务器地址
 port: ## redis服务开放端口
 cache:
 # 缓存类型 redis、none(不使用缓存)
 type: redis
 cloud:
 nacos:
 discovery:
 enabled: true
 server-addr: ${nacos.config.server-addr}
 namespace: ${nacos.config.namespace}
 # group:
 sentinel:
 enabled: false
macula:
 security:
 ignore-urls:
 - /swagger-ui/index.html
 - /v3/api-docs/swagger-config
 cloud:
 iam:
 issuer-uri: http://127.0.0.1:9010

mybatis-plus:
 configuration:
 # 这个配置会将执行的sql打印出来，在开发或测试的时候可以用
 log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
 type-handlers-package: dev.macula.boot.starter.mp.handler

feign:
 httpclient:
 enabled: false
 max-connections: 200 # 线程池最大连接数，默认200
 time-to-live: 900 # 线程存活时间，单位秒，默认900
 connection-timeout: 2000 # 新建连接超时时间，单位ms, 默认2000
 follow-redirects: true # 是否允许重定向，默认true
 disable-ssl-validation: false # 是否禁止SSL检查， 默认false
 okhttp:
 read-timeout: 60s # 请求超时时间，Duration配置方式
 okhttp:
 enabled: true

seata:
 enabled: false

springdoc:
 api-docs:
 enabled: true # 默认是true，用于开关API文档
 swagger-ui:
 enabled: true # 默认是true，用于开关API UI

server:
 servlet:
 encoding:
 force: true

logging:
 level:
 root: info
 dev.macula.cloud: debug
 file:
 name: ${user.home}/logs/${spring.application.name}/${spring.application.name}.log

修改macula-cloud-gateway 项目bootstrap.yml配置

server:
 port: 9000

spring:
 profiles:
 active: dev ## 指定程序以dev环境启动
 application:
 name: macula-cloud-gateway
 cloud:
 nacos:
 username: ${nacos.username}
 password: ${nacos.password}
 config:
 server-addr: ${nacos.config.server-addr}
 namespace: ${nacos.config.namespace}
 # group:
 refresh-enabled: true
 file-extension: yml

---
spring:
 config:
 activate:
 on-profile: dev
nacos:
 username: ## dev环境的nacos用户名
 password: ## dev环境的nacos密码
 config:
 server-addr: ## dev环境的nacos服务地址
 namespace: ## dev环境的nacos命名空间

修改macula-cloud-gateway 项目application.yml配置

spring:
 cloud:
 nacos:
 discovery:
 enabled: true
 server-addr: ${nacos.config.server-addr}
 namespace: ${nacos.config.namespace}
 # group:
 gateway:
 routes:
 - id: macula-cloud-system
 uri: lb://macula-cloud-system
 predicates:
 - Path=/system/**
 filters:
 - StripPrefix=1
 security:
 oauth2:
 resourceserver:
 opaquetoken:
 client-id: ## iam申请的客户端id
 client-secret: ## iam申请指定客户端id的密钥
 introspection-uri: http://127.0.0.1:9010/oauth2/introspect ## iam的提供的token认证introspect接口
 redis:
 database: 0
 host: ## gateway的redis服务器地址
 port: ## system的redis服务开放端口
 system:
 database: 0
 host: ## system的redis服务器地址 
 port: ## system的redis服务开放端口

macula:
 gateway:
 sign-switch: true # 接口签名全局开关，默认true
 force-sign: false # 是否强制校验指定URL的接口签名，默认false
 crypto-switch: true # 接口加解密全局开关，默认true
 force-crypto: false # 是否强制校验指定URL的接口要不要加解密，默认false
 protect-urls: # 需要保护的URL，前端可通过/gateway/protect/urls获取
 crypto: # 加密
 - /system/api/v1/app
 sign: # 签名
 - /system/api/v1/app
 security:
 only-auth-urls: /mallapi/**
 ignore-urls:
 - /system/api/token
 - /system/api/token/introspect

logging:
 level:
 root: info
 dev.macula.cloud: debug
 file:
 name: ${user.home}/logs/${spring.application.name}/${spring.application.name}.log

修改macula-cloud-system 项目bootstrap.yml配置

server:
 port: 8081

spring:
 profiles:
 active: dev ## 指定程序以dev环境启动
 application:
 name: macula-cloud-system
 cloud:
 nacos:
 username: ${nacos.username}
 password: ${nacos.password}
 config:
 server-addr: ${nacos.config.server-addr}
 namespace: ${nacos.config.namespace}
 # group:
 refresh-enabled: true
 file-extension: yml

---
spring:
 config:
 activate:
 on-profile: dev
nacos:
 username: ## dev环境的nacos用户名
 password: ## dev环境的nacos密码
 config:
 server-addr: ## dev环境的nacos服务地址
 namespace: ## dev环境的nacos命名空间

修改macula-cloud-system 项目application.yml配置

spring:
 datasource:
 type: com.alibaba.druid.pool.DruidDataSource
 driver-class-name: com.mysql.cj.jdbc.Driver
 url: jdbc:mysql://127.0.0.1:3306/macula-system?zeroDateTimeBehavior=convertToNull&useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&autoReconnect=true ## mysql数据库地址及数据库名
 username: ## mysql数据库用户名
 password: ## mysql数据库密码
 redis:
 database: 0
 host: ## redis服务器地址
 port: ## redis服务开放端口
 cache:
 # 缓存类型 redis、none(不使用缓存)
 type: redis
 security:
 oauth2:
 resourceserver:
 jwt:
 jwk-set-uri: http://127.0.0.1:9000/oauth2/jwks ## gateway开放出来的jwks获取路径
 cloud:
 nacos:
 discovery:
 enabled: true
 server-addr: ${nacos.config.server-addr}
 namespace: ${nacos.config.namespace}
 # group:
 metadata:
 version: v1
 sentinel:
 enabled: false
macula:
 security:
 ignore-urls:
 - /api/token
 - /api/token/**
 - /swagger-ui/index.html
 - /v3/api-docs/swagger-config

mybatis-plus:
 type-handlers-package: dev.macula.boot.starter.mp.handler

feign:
 httpclient:
 enabled: false
 max-connections: 200 # 线程池最大连接数，默认200
 time-to-live: 900 # 线程存活时间，单位秒，默认900
 connection-timeout: 2000 # 新建连接超时时间，单位ms, 默认2000
 follow-redirects: true # 是否允许重定向，默认true
 disable-ssl-validation: false # 是否禁止SSL检查， 默认false
 okhttp:
 read-timeout: 60s # 请求超时时间，Duration配置方式
 okhttp:
 enabled: true

seata:
 enabled: false

springdoc:
 api-docs:
 enabled: true # 默认是true，用于开关API文档
 swagger-ui:
 enabled: true # 默认是true，用于开关API UI

server:
 servlet:
 encoding:
 force: true

logging:
 level:
 root: info
 dev.macula.cloud: debug
 file:
 name: ${user.home}/logs/${spring.application.name}/${spring.application.name}.log

创建应用平台

Mon, 01 Jan 0001 00:00:00 +0000

（1）创建macula-samples平台

使用脚手架构创建macula-samples应用平台，如下所示：

mvn archetype:generate \
 -DgroupId=dev.macula.samples	\	# 你的应用的GroupID
 -DartifactId=macula-samples	\	# 你的应用的ArtifactId
 -Dversion=1.0.0-SNAPSHOT \		# 你的应用的版本号
 -DarchetypeArtifactId=macula-boot-archetype \ 
 -DarchetypeGroupId=dev.macula.boot \
 -DarchetypeVersion=5.0.6 \
 -Dgitignore=.gitignore -DinteractiveMode=false

或者使用git clone拉取sample相关代码

## samples代码
git clone https://github.com/macula-projects/macula-samples.git

说明：应用平台的项目结构、应用分层以及项目分包，框架规约中已经说明，不再赘述。

（2）应用平台接入Macula平台

macula-samples应用平台要复用Macula平台的认证服务、系统服务等能力，需要接入Macula平台，成为其中的一个租户。接入涉及的步骤如下：

Macula平台管理员登录MaculaCloudAdmin管理后台，创建租户（macula-samples应用平台）以及对应的租户管理员
macula-samples租户管理员登录MaculaCloudAdmin管理后台，创建当前租户下的应用、菜单、角色，获取ak和sk（macula-samples-admin-bff应用对应的ak/sk）
macula-samples租户管理员登录MaculaCloudAdmin管理后台，创建接入Macula平台认证服务所需的client客户端，获取client_id和client_secret

（3）运行macula-samples平台

（平台本地运行需要修改的配置，都需要明确标注说明，如数据库、缓存、注册中心、配置中心、消息队列等【文字+截图】）

修改macula-samples-admin-bff的配置文件，配置macula cloud的网关地址和ak/sk

macula:
 cloud:
 endpoint: http://127.0.0.1:9000  # macula cloud网关地址
 app-key: ${spring.application.name}
 secret-key: 待修改

修改macula-samples-admin登录配置文件，配置client_id/client_secret

macula-samples-admin/src/views/common/login/components/passwordForm.vue

var data = {
 username: this.form.user,
 password: this.form.password,
 grant_type: 'password',
 client_id: '待修改',
 client_secret: '待修改',
 scope: 'message.read message.write userinfo'
}

修改macula-samples-admin项目菜单的隐藏逻辑，macula-samples-admin/src/layout/index.vue

//处理隐藏
if (!item.meta.visible || item.meta.type == "BUTTON") {
 return false
}
改为：
//处理隐藏
if (item.meta.hidden || item.meta.type == "BUTTON") {
 return false
}

修改macula-samples-admin项目认证中心地址，.env.{环境变量}

VITE_APP_IAM_URL=http://localhost:9010
改为：
VITE_APP_IAM_URL=iam认证服务的真实地址（默认使用macula-cloud-iam项目的启动则为http://localhost:9010）

修改macula-samples-gateway项目共享redis和introspection接口地址：

spring:
 redis: # 网关自己的redis配置
 database: 0
 host: 127.0.0.1
 port: 6379
 system: # macula-cloud的system模块的redis配置
 database: 0
 host: 127.0.0.1
 port: 6379
 security:
 oauth2:
 resourceserver:
 opaquetoken:
 client-id: ***** ##（iam认证服务的客户端id，可看sys_oauth2_client表的client_id字段）
 client-secret: ***** ##（iam认证服务的客户端密码，可看sys_oauth2_client表的client_secret字段）
 introspection-uri: ## iam认证服务的token认证角色真实地址（默认使用macula-cloud-iam项目的启动则为http://localhost:9010/oauth2/introspect）

初始化数据库表

找到macula-samples-service1/docs/macula-samples-service1.sql，创建数据库，导入SQL创建示例表
分别启动macula-samples-admin、macula-samples-gateway、macula-samples-admin-bff、macula-samples-service1，成功运行效果参考以下集成测试章节。

创建服务模块

Mon, 01 Jan 0001 00:00:00 +0000

概述

针对在macula-samples平台中创建业务微服务macula-samples-service1案例的开发过程进行说明。

（1）业务需求说明

实现一个简单的应用与秘钥的管理功能。

（2）后端开发流程

创建macula-samples-service1

（pom文件引入需要的starter依赖、修改macula-samples平台上下文的PaaS组件配置）

<!-- web应用基础依赖包， 统一处理返回对象及异常等 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-web</artifactId>
</dependency>
<!-- 应用安全基础依赖包， 主要获取用户上下文及接口安全拦截等 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-security</artifactId>
</dependency>
<!-- 基于swgger的doc 基础依赖包 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-springdoc</artifactId>
</dependency>
<!-- mysql,druid,mybatis-plus 组成的基础依赖包 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-mybatis-plus</artifactId>
</dependency>
<!-- 基于mapstruct 基础依赖包 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-mapstruct</artifactId>
</dependency>
<!-- 基于redission组成的基础依赖包 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-redis</artifactId>
</dependency>
<!-- alibaba 微服务治理体系组成的基础依赖包 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-cloud-alibaba</artifactId>
</dependency>
<!-- Macula V5 获取应用菜单及登录用户相关信息必须依赖 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-system</artifactId>
</dependency>
<!-- Macula V5 规范的应用分层实践依赖 -->
<dependency>
 <groupId>dev.macula.samples</groupId>
 <artifactId>macula-samples-service1-api</artifactId>
 <version>${project.version}</version>
</dependency>

数据库表设计

应用实体表：

运行与测试

Mon, 01 Jan 0001 00:00:00 +0000

概述

在本地环境运行与测试

（1）准备工作

使用脚手架构创建macula-samples，如下所示：

mvn archetype:generate \
 -DgroupId=dev.macula.samples	\	# 你的应用的GroupID
 -DartifactId=macula-samples	\	# 你的应用的ArtifactId
 -Dversion=1.0.0-SNAPSHOT \		# 你的应用的版本号
 -DarchetypeArtifactId=macula-boot-archetype \ 
 -DarchetypeGroupId=dev.macula.boot \
 -DarchetypeVersion=5.0.6 \
 -Dgitignore=.gitignore -DinteractiveMode=false

或者拉取github macula-samples

## samples代码
git clone https://github.com/macula-projects/macula-samples.git

idea打开项目

加载maven，创建新service

在根目录pom.xml修改module配置

创建service的基础依赖api

添加相关依赖编写相关代码，如：创建服务模块所述

（2）启动服务

（3）API测试

关闭security拦截

测试无拦截api

打开security拦截

打包部署

Mon, 01 Jan 0001 00:00:00 +0000

（1）POM文件标准说明

在POM文件中，使用profile元素来定义特定的环境变量配置。profile元素允许您根据不同的环境（例如开发、测试、准生产、生产）为项目定义不同的配置。以下是对POM文件中profile环境变量的标准说明：

profile元素：在POM文件中，使用profile元素来定义一个或多个环境配置。每个profile元素包含一个唯一的id，用于标识该配置。
activation元素：在profile元素中，可以使用activation元素来指定激活该配置的条件。例如，您可以基于操作系统、Java版本、Maven版本等条件来激活特定的配置。
properties元素：在profile元素中，可以使用properties元素来定义环境变量。这些变量可以在项目中的其他地方引用。如下bootstrap.yml中就定义不同环境下的nacos链接信息。

server:
 port: 8081

spring:
 profiles:
 active: @profile.active@
 application:
 name: macula-cloud-system
 cloud:
 nacos:
 username: ${nacos.username}
 password: ${nacos.password}
 config:
 server-addr: ${nacos.config.server-addr}
 namespace: ${nacos.config.namespace}
 # group:
 refresh-enabled: true
 file-extension: yml

# 和环境有关的配置信息，不同环境覆盖此处的配置
nacos:
 username: nacos
 password: nacos
 config:
 server-addr: 127.0.0.1:8848
 namespace: MACULA5

---
spring:
 config:
 activate:
 on-profile: dev
nacos:
 username: maculav5
 password: *****
 config:
 server-addr: 127.0.0.1:8848
 namespace: maculav5-dev


---
spring:
 config:
 activate:
 on-profile: test
nacos:
 username: maculav5
 password: ******
 config:
 server-addr: 127.0.0.1:8848
 namespace: maculav5-test


---
spring:
 config:
 activate:
 on-profile: staging
nacos:
 username: maculav5
 password: ******
 config:
 server-addr: 127.0.0.1:8848
 namespace: maculav5-staging

---
spring:
 config:
 activate:
 on-profile: prd
nacos:
 username: itp
 password: ******
 config:
 server-addr: 127.0.0.1:8848
 namespace: maculav5

（2）虚拟机打包部署

以macula-cloud-iam服务部署为例