doc(readme): 优化使用说明

2026-03-22 06:15:10 +08:00 · 2024-06-05 14:41:57 +08:00
parent dda983c9e8
commit ec7d38f9dc
3 changed files with 206 additions and 48 deletions
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Jhinno OpenAPI SDK for Java
+# 1. Jhinno OpenAPI SDK for Java

 针对Java的景行API SDK使Java开发人员能够轻松使用景行API接口。您可以在几分钟内开始通过Maven或jar文件使用它。

@@ -7,21 +7,26 @@
 - [最新jar包：jhinno-openapi-java-sdk-1.0.0.jar](https://jhinno-jenkins.yuchat.top/job/jhinno-openapi-java-sdk/lastSuccessfulBuild/artifact/target/jhinno-openapi-java-sdk-1.0.0.jar)
 - [最新源码包：jhinno-openapi-java-sdk-1.0.0-sources.jar](https://jhinno-jenkins.yuchat.top/job/jhinno-openapi-java-sdk/lastSuccessfulBuild/artifact/target/jhinno-openapi-java-sdk-1.0.0-sources.jar)

-## 必要条件
+## 1.1 必要条件

 - Java 1.8 or later
 - Maven

-## 支持的Appform的版本
+## 1.2 支持的Appform的版本

 1. JH_Appform_6.0_Release
 2. JH_Appform_6.0_SP1_Release
+3. JH_Appform_6.1_Release

-## 安装
+# 2. 快速开始

-建议在您的项目中使用Jhinno OpenAPI SDK for Java的方法是从Maven中使用它。导入方法如下：
+## 2.1 SpringBoot

-方法一：通过Maven仓库安装
+### 2.1.1 安装
+
+建议在您的项目中使用Jhinno OpenAPI SDK for Java的方法是从Maven中使用它。：
+
+#### 方法一：通过Maven仓库安装

 > 添加仓库地址（改方案为备用方案，后续会上传至Maven中央仓库，目前不影响正常使用）

@@ -36,68 +41,204 @@
 </repositories>
 ```

-添加依赖
+#### 方法二：通过命令将jar包导入本地Maven仓库
+
+```shell
+
+# SDK Client的jar包的导入，其中<path-to-dir>为jar的路径，<path-to-dir>为jar包路径
+mvn org.apache.maven.plugins:maven-install-plugin:3.1.1:install-file -Dfile="<path-to-dir>/jhinno-openapi-java-sdk-1.0.0.jar" -Dsources="<path-to-dir>/jhinno-openapi-java-sdk-1.0.0-sources.jar"
+# 例如
+mvn org.apache.maven.plugins:maven-install-plugin:3.1.1:install-file -Dfile="E:/下载/jhinno-openapi-java-sdk-1.0.0.jar" -Dsources="E:/下载/jhinno-openapi-java-sdk-1.0.0-sources.jar"
+
+# SDK SpringBoot Starter的jar包的导入，其中<path-to-dir>为jar的路径，<path-to-dir>为jar包路径
+mvn org.apache.maven.plugins:maven-install-plugin:3.1.1:install-file -Dfile="<path-to-dir>/jhinno-openapi-sdk-spring-boot-starter-x.x.x.jar" -Dsources="<path-to-dir>/jhinno-openapi-sdk-spring-boot-starter-x.x.x-sources.jar"
+# 例如
+mvn org.apache.maven.plugins:maven-install-plugin:3.1.1:install-file -Dfile="E:/下载/jhinno-openapi-sdk-spring-boot-starter-1.0.1.jar" -Dsources="E:/下载/jhinno-openapi-sdk-spring-boot-starter-1.0.1-sources.jar"
+```
+
+> 注:
+> - jhinno-openapi-java-sdk-x.x.x.jar 为SDK的jar包。
+> - jhinno-openapi-java-sdk-x.x.x-sources.jar 为源码包，添加可方便查看SDK代码的注释。
+> - jhinno-openapi-sdk-spring-boot-starter-x.x.x.jar 为SDK的spring-boot-starter的jar包。
+> - jhinno-openapi-sdk-spring-boot-starter-1.0.1-sources.jar 为SDK的spring-boot-starter的源码包。
+
+### 2.1.2 引入`jhinno-openapi-sdk-spring-boot-starter`坐标

 ```xml

 <dependency>
    <groupId>com.jhinno</groupId>
-    <artifactId>jhinno-openapi-java-sdk</artifactId>
-    <version>1.0.0</version>
+    <artifactId>jhinno-openapi-sdk-spring-boot-starter</artifactId>
+    <version>1.0.1</version>
 </dependency>
 ```

-方法二：通过命令将jar包导入本地Maven仓库
+### 2.1.3 配置
+
+在SpringBoot的`application.properties`或`application.yml`里面配置
+
+#### 2.1.3.1  application.yaml
+
+```yaml
+jhinno:
+  openapi:
+    server-url: https://{appform服务器的地址}/appform
+    used-server-time: true
+```
+
+#### 2.1.3.2  application.properties
+
+```properties
+jhinno.openapi.server-url=https://{appform服务器的地址}/appform
+jhinno.openapi.used-server-time=true
+```
+
+> 注：
+> - 其中`jhinno.openapi.server-url`为景行接口服务的BaseUrl；
+> - `jhinno.openapi.used-server-time`是否获取服务器时间来请求token，关闭可提高获取token的时间，但打开有可能因为服务器时间不准确而导致token获取失败的问题。
+> - 更多配置见`com.jhinno.sdk.openapi.autoconfigure.JHOpenapiProperties`源码。
+
+### 2.1.4 使用
+
+在`com.jhinno.sdk.openapi.api`包下面对应`app`、`data`、`file`、`job`、`organization`这几个子包，分别代表景行`Appform`
+的应用、作业数据、文件、作业操作、组织等接口资源。开发者只需要使用接口的执行器（`JHxxxApiExecution`
+）即可使用资源，如：`JHFileApiExecution`
+
+```java
+public class DemoUserSDK {
+
+    /**
+     * 注入要调用的执行器
+     */
+    @Autowired
+    private JHFileApiExecution fileApiExecution;
+
+    void contextLoads() {
+
+        // 调用执行其中想要调用的方法
+        List<FileInfo> list = fileApiExecution.getFileList("jhadmin", "$HOME");
+        System.out.println(list);
+    }
+}
+```
+
+## 2.2 Spring
+
+### 2.2.1 安装
+
+建议在您的项目中使用Jhinno OpenAPI SDK for Java的方法是从Maven中使用它。：
+
+#### 方法一：通过Maven仓库安装
+
+> 添加仓库地址（改方案为备用方案，后续会上传至Maven中央仓库，目前不影响正常使用）
+
+```xml
+
+<repositories>
+    <repository>
+        <id>jhinno-nexus</id>
+        <name>jhinno-nexus</name>
+        <url>https://jhinno-nexus.yuchat.top/repository/maven-releases</url>
+    </repository>
+</repositories>
+```
+
+#### 方法二：通过命令将jar包导入本地Maven仓库

 ```shell
-# 其中<path-to-dir>为jar的路径，<path-to-dir>为jar包路径
+
+# SDK Client的jar包的导入，其中<path-to-dir>为jar的路径，<path-to-dir>为jar包路径
 mvn org.apache.maven.plugins:maven-install-plugin:3.1.1:install-file -Dfile="<path-to-dir>/jhinno-openapi-java-sdk-1.0.0.jar" -Dsources="<path-to-dir>/jhinno-openapi-java-sdk-1.0.0-sources.jar"
 # 例如
 mvn org.apache.maven.plugins:maven-install-plugin:3.1.1:install-file -Dfile="E:/下载/jhinno-openapi-java-sdk-1.0.0.jar" -Dsources="E:/下载/jhinno-openapi-java-sdk-1.0.0-sources.jar"
 ```

-> 注: 
+> 注:
 > - jhinno-openapi-java-sdk-x.x.x.jar 为SDK的jar包。
 > - jhinno-openapi-java-sdk-x.x.x-sources.jar 为源码包，添加可方便查看SDK代码的注释。

-然后在`pom.xml`添加
+### 2.2.2 引入`jhinno-openapi-java-sdk`坐标

 ```xml

 <dependency>
    <groupId>com.jhinno</groupId>
    <artifactId>jhinno-openapi-java-sdk</artifactId>
-    <version>1.0.0</version>
+    <version>1.0.1</version>
 </dependency>
 ```

-方法三：直接在`pom.xml`引用jar(改方法可能会出现一些莫名其妙的问题，所以不建议使用)
+### 2.2.3 配置
+
+spring.xml添加以下内容

 ```xml
-<!-- 其中{path-to-file}为jar的位置 -->
+<?xml version="1.0" encoding="utf-8"?>
+<beans>
+    <bean id="apiClient" class="com.jhinno.sdk.openapi.client.JHApiClient">
+        <property name="baseUrl" value="https://172.17.0.5/appform"/>
+    </bean>
+    <bean id="appApiExecution" class="com.jhinno.sdk.openapi.api.app.JHAppApiExecution">
+        <constructor-arg ref="apiClient"/>
+    </bean>
+    <bean id="dataApiExecution" class="com.jhinno.sdk.openapi.api.data.JHDataApiExecution">
+        <constructor-arg ref="apiClient"/>
+    </bean>
+    <bean id="fileApiExecution" class="com.jhinno.sdk.openapi.api.file.JHFileApiExecution">
+        <constructor-arg ref="apiClient"/>
+    </bean>
+    <bean id="jhJobApiExecution" class="com.jhinno.sdk.openapi.api.job.JHJobApiExecution">
+        <constructor-arg ref="apiClient"/>
+    </bean>
+    <bean id="departmentApiExecution" class="com.jhinno.sdk.openapi.api.organization.JHDepartmentApiExecution">
+        <constructor-arg ref="apiClient"/>
+    </bean>
+    <bean id="userApiExecution" class="com.jhinno.sdk.openapi.api.organization.JHUserApiExecution">
+        <constructor-arg ref="apiClient"/>
+    </bean>
+</beans>
+```
+
+### 2.2.4 使用
+
+在`com.jhinno.sdk.openapi.api`包下面对应`app`、`data`、`file`、`job`、`organization`这几个子包，分别代表景行`Appform`
+的应用、作业数据、文件、作业操作、组织等接口资源。开发者只需要使用接口的执行器（`JHxxxApiExecution`
+）即可使用资源，如：`JHAppApiExecution`
+
+```java
+public class DemoUserSDK {
+
+    /**
+     * 注入要调用的执行器
+     */
+    @Autowired
+    private JHFileApiExecution fileApiExecution;
+
+    void contextLoads() {
+
+        // 调用执行其中想要调用的方法
+        List<FileInfo> list = fileApiExecution.getFileList("jhadmin", "$HOME");
+        System.out.println(list);
+    }
+}
+```
+
+## 2.3 普通java项目
+
+### 2.3.1 安装
+
+- 同 2.2.1 安装一样 
+
+### 2.3.2 引入`jhinno-openapi-java-sdk`坐标
+```xml
+
 <dependency>
    <groupId>com.jhinno</groupId>
    <artifactId>jhinno-openapi-java-sdk</artifactId>
-    <version>1.0.0</version>
-    <scope>system</scope>
-    <systemPath>{path-to-file}</systemPath>
+    <version>1.0.1</version>
 </dependency>
 ```
-
-例如
-
-```xml
-<!-- 其中{path-to-file}为jar的位置 -->
-<dependency>
-    <groupId>com.jhinno</groupId>
-    <artifactId>jhinno-openapi-java-sdk</artifactId>
-    <version>1.0.0</version>
-    <scope>system</scope>
-    <systemPath>D:/jar/jhinno-openapi-java-sdk-1.0.0.jar</systemPath>
-</dependency>
-```
-
-## 使用
+### 2.3.3 使用

 在`com.jhinno.sdk.openapi.api`包下面对应`app`、`data`、`file`、`job`、`organization`这几个子包，分别代表景行`Appform`
 的应用、作业数据、文件、作业操作、组织等接口资源。开发者只需要使用接口的执行器（`JHxxxApiExecution`
@@ -137,7 +278,7 @@ public class DemoUserSDK {

 ```

-## 支持SDK的扩展
+# 3. 支持SDK的扩展

 如果是基于景行定制的接口，本SDK没有包含这些方法，因此您可以基于`JHApiExecution`快速进行扩展，具体的扩展步骤如下：

@@ -170,7 +311,7 @@ public class JHAppApiExecution extends JHApiExecution {

 ```

-## 构建
+# 4. 构建

 一旦您检出代码，就可以使用Maven构建它。使用以下命令进行构建：

@@ -178,17 +319,17 @@ public class JHAppApiExecution extends JHApiExecution {
 mvn clean package -DskipTests -P product
 ```

-## 代码贡献
+# 5. 代码贡献

 - 代码必须格式化，使用IDEA自带的格式即可；
 - 请求路径必须放在一个单独的const类中统一维护，具体可参考现有代码提交；
 - 封装新的接口是需要继承`JHApiExecution`，调用父类的辅助方法辅助封装；

-## 作者
+# 6. 作者

 - [yanlongqi](https://github.com/yanlongqi)

-## 支持
+# 7. 支持

 - 电话（同微信）：18794888087
 - 邮箱：lqyan@jhinno.com