1. 项目背景与核心价值最近在对接泛微E9系统的过程中发现很多开发者对Token认证和流程创建的完整链路存在困惑。作为一套广泛使用的OA系统泛微E9的接口调用与常规HTTP API存在显著差异。本文将基于Spring Boot框架完整演示从Token获取到流程创建的全过程包含实际开发中容易踩坑的细节处理。这个方案特别适合需要将业务系统与泛微OA进行深度集成的场景比如人事系统自动发起请假/报销流程ERP系统生成采购审批单据客服系统创建工单并同步至OA2. 环境准备与基础配置2.1 必要依赖配置在Spring Boot项目的pom.xml中添加以下核心依赖dependencies !-- Spring Web基础依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- HTTP客户端 -- dependency groupIdorg.apache.httpcomponents/groupId artifactIdhttpclient/artifactId version4.5.13/version /dependency !-- JSON处理 -- dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency /dependencies2.2 泛微接口配置项在application.yml中配置泛微服务器信息weaver: e9: base-url: http://oa.example.com/api auth: username: system_account password: encrypted_password default-sec-code: DEFAULT_SEC_CODE注意password建议使用Jasypt等工具加密存储避免明文密码泄露风险3. Token认证机制实现3.1 认证接口分析泛微E9的Token认证接口通常为/rest/token需要POST方式提交以下参数参数名必填说明loginid是登录账号password是密码明文secode否安全码如有动态令牌3.2 认证服务实现创建TokenService处理认证逻辑Service public class TokenService { Value(${weaver.e9.base-url}) private String baseUrl; Value(${weaver.e9.auth.username}) private String username; Value(${weaver.e9.auth.password}) private String password; Value(${weaver.e9.default-sec-code}) private String secCode; public String getToken() { CloseableHttpClient httpClient HttpClients.createDefault(); HttpPost httpPost new HttpPost(baseUrl /rest/token); // 构建表单参数 ListNameValuePair params new ArrayList(); params.add(new BasicNameValuePair(loginid, username)); params.add(new BasicNameValuePair(password, password)); if(StringUtils.isNotBlank(secCode)) { params.add(new BasicNameValuePair(secode, secCode)); } try { httpPost.setEntity(new UrlEncodedFormEntity(params, UTF-8)); CloseableHttpResponse response httpClient.execute(httpPost); // 解析响应 String responseBody EntityUtils.toString(response.getEntity()); JSONObject json new JSONObject(responseBody); if(1.equals(json.getString(status))) { return json.getString(token); } else { throw new RuntimeException(认证失败: json.getString(message)); } } catch (Exception e) { throw new RuntimeException(Token获取异常, e); } } }3.3 Token管理策略在实际项目中建议采用以下优化策略Token缓存使用Redis缓存Token设置合理过期时间通常比接口返回的expires_in短5分钟失败重试当Token失效时自动重试一次获取新Token熔断机制连续认证失败时触发熔断避免系统雪崩4. 流程创建实现4.1 流程接口规范泛微E9创建流程的主要接口为/workflow/request需要以下关键参数{ requestid: , workflowid: 流程ID, formid: 表单ID, isupate: 0, maindata: [ { fieldname: 字段1, fieldvalue: 值1 } ] }4.2 流程服务实现创建WorkflowService处理流程操作Service public class WorkflowService { Autowired private TokenService tokenService; Value(${weaver.e9.base-url}) private String baseUrl; public String createWorkflow(String workflowId, String formId, MapString, Object fieldValues) { String token tokenService.getToken(); JSONObject requestBody new JSONObject(); requestBody.put(requestid, ); requestBody.put(workflowid, workflowId); requestBody.put(formid, formId); requestBody.put(isupate, 0); JSONArray mainData new JSONArray(); fieldValues.forEach((field, value) - { JSONObject item new JSONObject(); item.put(fieldname, field); item.put(fieldvalue, value); mainData.put(item); }); requestBody.put(maindata, mainData); CloseableHttpClient httpClient HttpClients.createDefault(); HttpPost httpPost new HttpPost(baseUrl /workflow/request); try { // 设置请求头 httpPost.setHeader(Content-Type, application/json); httpPost.setHeader(token, token); // 设置请求体 httpPost.setEntity(new StringEntity(requestBody.toString(), UTF-8)); CloseableHttpResponse response httpClient.execute(httpPost); String responseBody EntityUtils.toString(response.getEntity()); JSONObject json new JSONObject(responseBody); if(1.equals(json.getString(status))) { return json.getString(requestid); } else { throw new RuntimeException(流程创建失败: json.getString(message)); } } catch (Exception e) { throw new RuntimeException(流程接口调用异常, e); } } }4.3 字段映射技巧泛微表单字段与实际业务字段的映射建议采用配置化方式管理workflow-mapping: leave-request: # 流程类型 workflow-id: 1001 form-id: 2001 field-mapping: applicant: field_1 leave-type: field_2 start-date: field_3 end-date: field_4 reason: field_55. 异常处理与调试技巧5.1 常见错误代码错误码含义解决方案1001Token无效重新获取Token2003流程不存在检查workflowid配置3005字段不存在核对表单字段映射4001权限不足检查账号权限5.2 日志记录建议在关键节点添加详细日志Slf4j Service public class WorkflowService { public String createWorkflow(...) { log.info(开始创建流程, workflowId: {}, formId: {}, workflowId, formId); try { // ...业务逻辑... log.debug(请求参数: {}, requestBody.toString()); // ...调用接口... log.info(流程创建成功, requestId: {}, json.getString(requestid)); return json.getString(requestid); } catch (Exception e) { log.error(流程创建异常, e); throw e; } } }5.3 接口调试工具推荐使用Postman进行接口调试可保存以下测试集合Token获取请求Method: POSTURL:{{baseUrl}}/rest/tokenBody: x-www-form-urlencodedloginid: 账号password: 密码流程创建请求Method: POSTURL:{{baseUrl}}/workflow/requestHeaders:token: {{token}}Content-Type: application/jsonBody: raw JSON6. 性能优化建议6.1 连接池配置优化HTTP连接池参数Configuration public class HttpClientConfig { Bean public CloseableHttpClient httpClient() { PoolingHttpClientConnectionManager connectionManager new PoolingHttpClientConnectionManager(); connectionManager.setMaxTotal(100); connectionManager.setDefaultMaxPerRoute(20); RequestConfig requestConfig RequestConfig.custom() .setConnectTimeout(5000) .setSocketTimeout(15000) .build(); return HttpClients.custom() .setConnectionManager(connectionManager) .setDefaultRequestConfig(requestConfig) .build(); } }6.2 异步处理方案对于大批量流程创建建议采用异步处理Async public FutureString asyncCreateWorkflow(String workflowId, String formId, MapString, Object fieldValues) { String requestId createWorkflow(workflowId, formId, fieldValues); return new AsyncResult(requestId); }6.3 结果回调机制对于长时间运行的流程建议实现状态回调RestController RequestMapping(/callback) public class CallbackController { PostMapping(/workflow) public ResponseEntity? handleCallback(RequestBody CallbackData data) { // 处理流程状态变更通知 workflowStatusService.updateStatus(data); return ResponseEntity.ok().build(); } }7. 安全增强措施7.1 请求签名验证在敏感操作中添加签名验证public void validateSignature(String token, String timestamp, String signature) { String serverSign DigestUtils.md5Hex(token timestamp secretKey); if(!serverSign.equals(signature)) { throw new SecurityException(签名验证失败); } }7.2 敏感数据加密对流程中的敏感字段进行加密处理public String encryptField(String value) { try { Cipher cipher Cipher.getInstance(AES/CBC/PKCS5Padding); // 初始化cipher... byte[] encrypted cipher.doFinal(value.getBytes()); return Base64.getEncoder().encodeToString(encrypted); } catch (Exception e) { throw new RuntimeException(加密失败, e); } }7.3 接口访问控制通过Spring Security限制访问权限Configuration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Override protected void configure(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers(/api/workflow/**).hasRole(OA_INTEGRATION) .anyRequest().authenticated() .and() .httpBasic(); } }8. 实际应用案例8.1 请假流程集成public String createLeaveRequest(LeaveApplication leave) { MapString, Object fields new HashMap(); fields.put(field_1, leave.getApplicant()); fields.put(field_2, leave.getType().name()); fields.put(field_3, leave.getStartDate()); fields.put(field_4, leave.getEndDate()); fields.put(field_5, leave.getReason()); return workflowService.createWorkflow( 1001, // 请假流程ID 2001, // 请假表单ID fields ); }8.2 采购审批集成public String createPurchaseRequest(PurchaseOrder order) { MapString, Object fields new HashMap(); fields.put(po_number, order.getNumber()); fields.put(total_amount, order.getTotalAmount()); fields.put(items, convertItemsToJson(order.getItems())); return workflowService.createWorkflow( 1002, // 采购流程ID 2002, // 采购表单ID fields ); }9. 扩展与进阶9.1 流程状态查询public String getWorkflowStatus(String requestId) { String token tokenService.getToken(); HttpGet httpGet new HttpGet(baseUrl /workflow/request?requestid requestId); httpGet.setHeader(token, token); // 执行请求并解析响应... }9.2 附件上传支持public void uploadAttachment(String requestId, MultipartFile file) { String token tokenService.getToken(); HttpPost httpPost new HttpPost(baseUrl /workflow/upload); MultipartEntityBuilder builder MultipartEntityBuilder.create(); builder.addTextBody(requestid, requestId); builder.addBinaryBody(file, file.getBytes(), ContentType.MULTIPART_FORM_DATA, file.getOriginalFilename()); httpPost.setEntity(builder.build()); httpPost.setHeader(token, token); // 执行上传... }9.3 批量操作优化对于批量创建流程的场景建议使用线程池控制并发数实现失败重试机制添加进度监控接口最终结果汇总报告public BatchResult batchCreateWorkflows(ListWorkflowRequest requests) { ExecutorService executor Executors.newFixedThreadPool(10); ListFutureSingleResult futures new ArrayList(); for(WorkflowRequest request : requests) { futures.add(executor.submit(() - { try { String requestId createWorkflow(...); return SingleResult.success(requestId); } catch (Exception e) { return SingleResult.fail(e.getMessage()); } })); } // 处理结果汇总... }