新增易方达接口以及添加claude技能
This commit is contained in:
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Skill(skill-creator)",
|
||||
"Bash(pandoc:*)",
|
||||
"Bash(python ooxml/scripts/unpack.py:*)",
|
||||
"Bash(npm install:*)",
|
||||
"Bash(node generate_doc.js:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,522 @@
|
||||
---
|
||||
name: fangjia-openapi-dev
|
||||
description: 房价开放平台(fangjia-open)接口开发技能。用于开发基于估家科技开放平台的RESTful API接口。当用户需要:(1) 开发新的OpenAPI接口,(2) 阅读接口需求文档并生成代码,(3) 生成OpenAPI接口文档,(4) 分析接口需求并给出开发建议时使用此技能。支持从Word/PDF需求文档自动提取接口信息、生成Controller/Service/DAO代码、生成API文档。
|
||||
---
|
||||
|
||||
# 估家科技OpenAPI接口开发
|
||||
|
||||
本技能帮助开发房价开放平台(fangjia-open)的RESTful API接口,包括需求分析、代码生成、文档编写全流程。
|
||||
|
||||
## 何时使用此技能
|
||||
|
||||
- 用户提供接口需求文档(Word/PDF/Markdown)
|
||||
- 用户要求开发新的OpenAPI接口
|
||||
- 用户需要生成API接口文档
|
||||
- 用户询问"如何开发XXX接口"
|
||||
|
||||
## 开发流程
|
||||
|
||||
### 阶段1:需求分析
|
||||
|
||||
**1.1 读取需求文档**
|
||||
|
||||
如果用户提供Word/PDF文档:
|
||||
```bash
|
||||
# 使用pandoc转换为Markdown
|
||||
pandoc "文档路径.docx" -o "文档路径.md"
|
||||
# 然后读取转换后的Markdown文件
|
||||
```
|
||||
|
||||
**1.2 提取关键信息**
|
||||
|
||||
从需求文档中提取:
|
||||
- 接口功能描述
|
||||
- 输入参数(参数名、类型、是否必填、说明)
|
||||
- 输出字段(字段名、类型、描述)
|
||||
- 业务逻辑要求
|
||||
|
||||
**1.3 检查缺失信息**
|
||||
|
||||
必须向用户确认以下信息(如果文档中没有):
|
||||
|
||||
| 信息项 | 询问示例 |
|
||||
|-------|---------|
|
||||
| **接口URL** | "文档中没有指定接口URL,建议使用 `/property/priceQuery`,您确认吗?" |
|
||||
| **数据来源** | "请问数据来自哪里?MongoDB的哪个Collection?还是MySQL的哪个表?" |
|
||||
| **Service层** | "是否有现成的Service可以调用?如果没有,需要在哪个业务模块下创建?" |
|
||||
| **DAO层** | "是否有现成的DAO?如果需要新建,数据库是MongoDB还是MySQL?" |
|
||||
|
||||
**1.4 给出合理性建议**
|
||||
|
||||
检查以下方面并给出建议:
|
||||
- ✅ 参数命名是否符合驼峰命名规范
|
||||
- ✅ 必填/可选参数设置是否合理
|
||||
- ✅ 返回字段是否完整(建议添加时间戳、匹配置信度等)
|
||||
- ✅ 是否考虑了异常情况(如地址未匹配)
|
||||
|
||||
---
|
||||
|
||||
### 阶段2:代码开发
|
||||
|
||||
按照顺序开发:**DAO → Service → Controller**
|
||||
|
||||
**注意**:由于返回字段使用下划线命名,通常**不需要创建专门的Model类**,直接使用`UniversalDto`封装返回结果。
|
||||
|
||||
**2.1 开发DAO层(如需要)**
|
||||
|
||||
- 优先询问是否有现成的DAO可用
|
||||
- 如需新建,位置:`projects/fangjia-dal/src/main/java/com/fangjia/dal/`
|
||||
- 根据数据库类型选择基类(AbstractMongoDao / AbstractSqlDao)
|
||||
|
||||
**2.2 开发Service层**
|
||||
|
||||
位置:`projects/fangjia-service/src/main/java/com/fangjia/service/{业务模块}/`
|
||||
|
||||
必须创建:
|
||||
1. Service接口 - 参考 [code-templates.md](references/code-templates.md) "Service 接口模板"
|
||||
2. Service实现类 - 参考 [code-templates.md](references/code-templates.md) "Service 实现类模板"
|
||||
|
||||
**注意**:
|
||||
- 必须提供setter方法进行依赖注入
|
||||
- 不需要使用注解(@Service等)
|
||||
- 不需要手动配置Spring Bean
|
||||
- 优先复用现有Service(见"常用Service参考"章节)
|
||||
|
||||
**2.3 开发Controller层**
|
||||
|
||||
位置:`projects/fangjia-open/src/main/java/com/fangjia/open/controllers/`
|
||||
|
||||
参考模板:[code-templates.md](references/code-templates.md) "Controller 模板"
|
||||
|
||||
**关键要点**:
|
||||
- 方法名必须以 `Action` 结尾
|
||||
- 添加 `@Authority(role = Role.USER)` 注解
|
||||
- 使用 `RestfulModelAndView` 作为返回值
|
||||
- 手动进行参数校验(使用 `StringUtils.isBlank` 等)
|
||||
- **不要**使用try-catch(有统一异常处理)
|
||||
|
||||
---
|
||||
|
||||
### 阶段3:生成API文档
|
||||
|
||||
**3.1 使用API文档模板**
|
||||
|
||||
API文档模板位于(**相对于skill目录**):`assets\估家科技开放接口文档-模版.docx`
|
||||
|
||||
**注意**:这是相对路径,完整路径为:
|
||||
```
|
||||
.claude/skills/fangjia-openapi-dev/assets/估家科技开放接口文档-模版.docx
|
||||
```
|
||||
|
||||
**3.2 生成文档内容**
|
||||
|
||||
按照模板格式生成:
|
||||
|
||||
1. **接口地址**:根据Controller和方法名确定URL
|
||||
2. **输入参数表格**:
|
||||
- 参数名
|
||||
- 参数类型(String/Integer/Float等)
|
||||
- 是否必填
|
||||
- 说明
|
||||
3. **响应参数表格**:
|
||||
- 名称
|
||||
- 类型
|
||||
- 描述
|
||||
4. **响应示例**:生成JSON格式示例
|
||||
|
||||
**3.3 文档生成方式**
|
||||
|
||||
### 方式1:使用docx-js生成(强烈推荐)
|
||||
|
||||
**重要**:为确保表格样式与模板完全一致,**强烈推荐**使用docx-js库直接生成Word文档。
|
||||
|
||||
使用pandoc转换可能导致:
|
||||
- ❌ 表格边框样式不一致
|
||||
- ❌ 表头背景色不匹配
|
||||
- ❌ 单元格内边距不同
|
||||
|
||||
参考代码示例:
|
||||
```javascript
|
||||
// 创建表格时指定边框样式
|
||||
const tableBorder = { style: BorderStyle.SINGLE, size: 6, color: "000000" };
|
||||
const cellBorders = { top: tableBorder, bottom: tableBorder, left: tableBorder, right: tableBorder };
|
||||
|
||||
new Table({
|
||||
columnWidths: [2340, 2340, 4680],
|
||||
margins: { top: 100, bottom: 100, left: 100, right: 100 },
|
||||
rows: [
|
||||
new TableRow({
|
||||
tableHeader: true,
|
||||
children: [
|
||||
new TableCell({
|
||||
borders: cellBorders,
|
||||
shading: { fill: "D3D3D3", type: ShadingType.CLEAR },
|
||||
children: [new Paragraph({
|
||||
alignment: AlignmentType.CENTER,
|
||||
children: [new TextRun({ text: "参数名", bold: true })]
|
||||
})]
|
||||
})
|
||||
]
|
||||
})
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
### 方式2:使用pandoc快速生成(仅供参考)
|
||||
|
||||
仅用于快速预览,**最终交付文档必须使用方式1**:
|
||||
```bash
|
||||
pandoc api-doc.md -o api-doc.docx --reference-doc=".claude/skills/fangjia-openapi-dev/assets/估家科技开放接口文档-模版.docx"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 开发规范
|
||||
|
||||
详见 [development-standards.md](references/development-standards.md)
|
||||
|
||||
### 关键规范速查
|
||||
|
||||
| 项目 | 规范 |
|
||||
|-----|------|
|
||||
| URL映射 | `XxxController.methodAction` → `/xxx/method` |
|
||||
| 返回格式 | `RestfulModelAndView` + `BasicModel` |
|
||||
| 参数校验 | 手动代码校验(`StringUtils.isBlank`) |
|
||||
| 依赖注入 | 提供setter方法,不使用注解 |
|
||||
| 异常处理 | 不需要try-catch |
|
||||
| 字符编码 | UTF-8 |
|
||||
|
||||
---
|
||||
|
||||
## 常用Service参考
|
||||
|
||||
开发接口时经常需要使用以下核心Service:
|
||||
|
||||
### 地址匹配相关
|
||||
|
||||
**AddressMatchProxyService** (`com.fangjia.service.api.AddressMatchProxyService`)
|
||||
|
||||
- `newMatch(String city, String address, String category, boolean useMap)`
|
||||
- 功能:地址匹配、property_type识别
|
||||
- 返回:JSONObject包含匹配结果(id, city, district, name, propertyType, street, township, credit等)
|
||||
- 示例:`addressMatchProxyService.newMatch(null, "上海市浦东新区唐安路199弄", null, true)`
|
||||
|
||||
### 房价查询相关
|
||||
|
||||
**DistrictStatService** (`com.fangjia.service.district.DistrictStatService`)
|
||||
|
||||
- `findLatestDistrictAvgPrice(String city, String region, String block, String name)`
|
||||
- 功能:查询最新小区均价
|
||||
- 返回:Integer(元/平方米)
|
||||
|
||||
- `findOneDistrictStatsSort(String city, String region, String name, Date weekend)`
|
||||
- 功能:查询指定时间的小区统计信息
|
||||
- 返回:DistrictStat对象(包含avgPrice, weekend等)
|
||||
|
||||
### 成交数据相关
|
||||
|
||||
**DealPriceService** (`com.fangjia.service.mongo.fangjia.DealPriceService`)
|
||||
|
||||
- `findHouseTradeHistoryLatest(DistrictKey key, int limit, boolean isVilla)`
|
||||
- 功能:查询最近成交记录
|
||||
- 用途:计算典型总价(找到成交单价最接近参考均价的记录)
|
||||
- 返回:List<DealPrice>(包含avgPrice, totalPrice, area, tradeDate等)
|
||||
|
||||
- `findDealPriceList(String city, String region, String districtName, Date startDate, Date endDate)`
|
||||
- 功能:查询指定时间范围的成交记录
|
||||
- 注意:日期参数不要传null,传明确的日期值
|
||||
- 返回:List<DealPrice>
|
||||
|
||||
### 小区数据相关
|
||||
|
||||
**DistrictService** (`com.fangjia.service.datastore.DistrictService`)
|
||||
|
||||
- `findById(String districtId)`
|
||||
- 功能:根据ID查询小区信息(权威数据)
|
||||
- 用途:地址匹配返回id后,查询权威的城市/区域/名称用于价格查询
|
||||
- 返回:District对象(包含city, region, name, block等)
|
||||
|
||||
### 区域价格相关
|
||||
|
||||
**RegionSellStatService** (`com.fangjia.service.mongo.fangjia.RegionSellStatService`)
|
||||
|
||||
- `findNewestRegionPrice(String city, String region)`
|
||||
- 功能:查询最新区域均价
|
||||
- 注意:必须先用RegionData.formatCity和formatRegion格式化城市/区域为简称
|
||||
- 返回:RegionSellStat对象(包含avgPrice, date, updateDate等)
|
||||
|
||||
### 使用示例
|
||||
|
||||
```java
|
||||
// 1. 地址匹配
|
||||
JSONObject matchResult = addressMatchProxyService.newMatch(null, address, null, true);
|
||||
String city = matchResult.optString("city");
|
||||
String name = matchResult.optString("name");
|
||||
String propertyType = matchResult.optString("propertyType");
|
||||
|
||||
// 2. 查询房价
|
||||
Integer avgPrice = districtStatService.findLatestDistrictAvgPrice(city, district, null, name);
|
||||
|
||||
// 3. 查询数据更新时间
|
||||
DistrictStat latestStat = districtStatService.findOneDistrictStatsSort(city, district, name, null);
|
||||
Date updateTime = latestStat.getWeekend();
|
||||
|
||||
// 4. 查询成交数据计算典型总价
|
||||
DistrictKey key = new DistrictKey(city, district, null, name);
|
||||
List<DealPrice> deals = dealPriceService.findHouseTradeHistoryLatest(key, 100, false);
|
||||
// 找到成交单价最接近参考均价的记录
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键开发经验
|
||||
|
||||
以下是实际开发中总结的关键技术要点,必须严格遵循:
|
||||
|
||||
### 1. 地址匹配接口使用模式 ⭐⭐⭐
|
||||
|
||||
**核心原则**:判断是否有 `id` 字段来确定匹配是否成功。
|
||||
|
||||
```java
|
||||
// 调用地址匹配服务
|
||||
JSONObject matchResult = addressMatchProxyService.newMatch(city, address, null, true);
|
||||
|
||||
// 关键:检查是否有id字段
|
||||
String id = (matchResult != null) ? matchResult.optString("id") : null;
|
||||
if (StringUtils.isBlank(id)) {
|
||||
// 没有id算匹配失败,需要调用标准化拆分
|
||||
return handleAddressStructure(city, address);
|
||||
}
|
||||
|
||||
// 有id表示匹配到具体POI,使用id查询权威数据
|
||||
District district = districtService.findById(id);
|
||||
```
|
||||
|
||||
**要点**:
|
||||
- ✅ 有 `id` 字段 → 匹配成功,匹配到具体POI(小区/写字楼/建筑)
|
||||
- ❌ 无 `id` 字段 → 匹配失败,调用 `addressStructure` 做标准化拆分
|
||||
|
||||
### 2. 直辖市特殊处理 ⭐⭐⭐
|
||||
|
||||
**问题**:直辖市的 `addressStructure` 返回结果中,城市名在 `province` 字段,不在 `city` 字段。
|
||||
|
||||
```java
|
||||
// addressStructure返回示例(上海):
|
||||
// { "province": "上海市", "city": "市辖区", "district": "浦东新区" }
|
||||
|
||||
// 正确处理方式
|
||||
String province = structureResult.optString("province");
|
||||
String cityField = structureResult.optString("city");
|
||||
|
||||
String structCity;
|
||||
if (ProvinceData.isGovernmentCity(province)) {
|
||||
// 直辖市:北京市、上海市、天津市、重庆市
|
||||
structCity = province;
|
||||
} else {
|
||||
structCity = cityField;
|
||||
}
|
||||
```
|
||||
|
||||
**适用范围**:北京、上海、天津、重庆
|
||||
|
||||
### 3. 数据来源分离原则 ⭐⭐⭐
|
||||
|
||||
**核心原则**:展示字段和查询字段使用不同的数据源。
|
||||
|
||||
```java
|
||||
// 从匹配结果获取展示用的数据(用户友好格式)
|
||||
String matchCity = matchResult.optString("city"); // "上海"
|
||||
String matchDistrict = matchResult.optString("district"); // "浦东"
|
||||
String matchName = matchResult.optString("name");
|
||||
|
||||
// 从District对象获取权威数据(用于查询)
|
||||
String districtCity = district.getCity(); // "上海市"
|
||||
String districtRegion = district.getRegion(); // "浦东新区"
|
||||
String districtName = district.getName();
|
||||
|
||||
// 返回给用户:使用匹配结果的数据
|
||||
result.append("city", matchCity);
|
||||
result.append("district", matchDistrict);
|
||||
result.append("community_name", matchName);
|
||||
|
||||
// 查询价格和成交数据:使用District对象的权威数据
|
||||
DistrictStat latestStat = districtStatService.findOneDistrictStatsSort(
|
||||
districtCity, districtRegion, districtName, null);
|
||||
```
|
||||
|
||||
**为什么分离**:
|
||||
- 展示数据:用户输入什么格式,返回什么格式("上海" vs "上海市")
|
||||
- 查询数据:使用数据库中存储的标准格式
|
||||
|
||||
### 4. 区域价格查询前必须格式化 ⭐⭐⭐
|
||||
|
||||
**问题**:区域价格查询必须使用城市和区域的简称,否则查不到数据。
|
||||
|
||||
```java
|
||||
// 错误示例 ❌
|
||||
RegionSellStat stat = regionSellStatService.findNewestRegionPrice(
|
||||
"上海市", "浦东新区"); // 查不到数据
|
||||
|
||||
// 正确示例 ✅
|
||||
String formattedCity = RegionData.formatCity("上海市"); // "上海"
|
||||
String formattedRegion = RegionData.formatRegion(formattedCity, "浦东新区"); // "浦东"
|
||||
RegionSellStat stat = regionSellStatService.findNewestRegionPrice(
|
||||
formattedCity, formattedRegion);
|
||||
```
|
||||
|
||||
**使用场景**:
|
||||
- 查询区域价格(`RegionSellStatService.findNewestRegionPrice`)
|
||||
- 任何需要使用城市/区域作为查询条件的场景
|
||||
|
||||
### 5. Service方法日期参数处理 ⭐⭐
|
||||
|
||||
**问题**:某些Service方法会直接将日期参数添加到查询条件,传 `null` 可能导致异常。
|
||||
|
||||
```java
|
||||
// 错误示例 ❌
|
||||
List<DealPrice> dealPrices = dealPriceService.findDealPriceList(
|
||||
city, region, name, startDate, null); // endDate传null可能有问题
|
||||
|
||||
// 正确示例 ✅
|
||||
Date halfYearAgo = new Date(System.currentTimeMillis() - 180L * 24 * 60 * 60 * 1000);
|
||||
Date now = new Date();
|
||||
List<DealPrice> dealPrices = dealPriceService.findDealPriceList(
|
||||
city, region, name, halfYearAgo, now);
|
||||
```
|
||||
|
||||
**建议**:始终传入明确的日期值,避免传 `null`。
|
||||
|
||||
### 6. 价格字段优先级 ⭐⭐
|
||||
|
||||
**规则**:`avg_price_2b` 字段优先于 `avgPrice` 字段。
|
||||
|
||||
```java
|
||||
// DistrictStat中有两个均价字段
|
||||
Integer avgPrice = null;
|
||||
if (latestStat.getAvg_price_2b() != null && latestStat.getAvg_price_2b() > 0) {
|
||||
avgPrice = latestStat.getAvg_price_2b(); // 优先使用
|
||||
} else if (latestStat.getAvgPrice() > 0) {
|
||||
avgPrice = latestStat.getAvgPrice(); // 降级使用
|
||||
}
|
||||
```
|
||||
|
||||
**原因**:`avg_price_2b` 是新版价格字段,数据更准确。
|
||||
|
||||
### 7. category字段判断POI类型 ⭐⭐
|
||||
|
||||
**规则**:使用 `category` 字段判断匹配结果的类型。
|
||||
|
||||
```java
|
||||
String category = matchResult.optString("category");
|
||||
|
||||
if ("district".equals(category)) {
|
||||
// 小区 → 输出房价
|
||||
result.append("property_type", "住宅");
|
||||
// 查询房价和成交数据
|
||||
} else if ("office".equals(category)) {
|
||||
// 写字楼 → 不输出房价
|
||||
result.append("property_type", "写字楼");
|
||||
} else {
|
||||
// 其他类型建筑
|
||||
String propertyType = matchResult.optString("propertyType");
|
||||
result.append("property_type", propertyType);
|
||||
}
|
||||
```
|
||||
|
||||
**常见值**:
|
||||
- `district` - 小区
|
||||
- `office` - 写字楼
|
||||
- 其他 - 使用 `propertyType` 字段判断
|
||||
|
||||
### 8. Controller参数必须使用@Param注解 ⭐
|
||||
|
||||
**规则**:所有Controller方法参数都需要 `@Param` 注解。
|
||||
|
||||
```java
|
||||
import org.sothis.web.mvc.annotation.Param;
|
||||
|
||||
public RestfulModelAndView matchAction(
|
||||
@Param(name = "address") String address,
|
||||
@Param(name = "city") String city) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:包路径是 `org.sothis.web.mvc.annotation.Param`,不是Spring的注解。
|
||||
|
||||
---
|
||||
|
||||
## 常见问题处理
|
||||
|
||||
### Q1: 返回数据格式规范
|
||||
|
||||
**重要**:接口返回的字段名使用**下划线分隔**,不使用驼峰命名。
|
||||
|
||||
- ✅ 正确:`community_name`, `reference_price`, `typical_total_price`
|
||||
- ❌ 错误:`communityName`, `referencePrice`, `typicalTotalPrice`
|
||||
|
||||
因此,**不要创建专门的Model类**,直接使用 `UniversalDto` 封装结果:
|
||||
|
||||
```java
|
||||
UniversalDto result = UniversalDto.newDto();
|
||||
result.append("community_name", "陆家嘴花园");
|
||||
result.append("city", "上海市");
|
||||
result.append("reference_price", 126000);
|
||||
result.append("update_time", "2026-01-31");
|
||||
mav.setModel(BasicModel.buildOKModel().setResult(result));
|
||||
```
|
||||
|
||||
### Q2: 如何处理参数校验?
|
||||
|
||||
手动代码校验,示例见 [development-standards.md](references/development-standards.md) "参数校验" 章节
|
||||
|
||||
### Q3: 需要配置Spring Bean吗?
|
||||
|
||||
不需要。约定大于配置,只要提供setter方法即可自动注入。
|
||||
|
||||
### Q4: 本地如何测试?
|
||||
|
||||
```bash
|
||||
cd deliverables/fangjiaopen
|
||||
mvn tomcat7:run
|
||||
# 访问: http://localhost:8032/{controller}/{action}?param=value&token=xxx
|
||||
```
|
||||
|
||||
### Q5: 如何构建部署?
|
||||
|
||||
```bash
|
||||
cd deliverables/fangjiaopen
|
||||
mvn clean package -Dmaven.test.skip=true
|
||||
# WAR包位置: target/fangjia-open.war
|
||||
# 后续通过Jenkins Pipeline自动部署到K8S
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流程总结
|
||||
|
||||
1. **读取需求** → 使用pandoc转换Word/PDF
|
||||
2. **分析需求** → 提取参数、字段、逻辑
|
||||
3. **询问确认** → URL、数据源、Service/DAO
|
||||
4. **给出建议** → 命名、字段、异常处理
|
||||
5. **生成代码** → DAO(如需要) → Service → Controller
|
||||
- 返回数据使用UniversalDto,字段名用下划线分隔
|
||||
- 优先复用现有Service(AddressMatchProxyService、DistrictStatService等)
|
||||
6. **生成文档** → 使用docx-js生成Word格式API文档(确保样式一致)
|
||||
7. **接口测试** → 参考 [API测试指南](references/api-testing-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## 参考资料
|
||||
|
||||
- **[代码模板](references/code-templates.md)** - Controller、Service代码模板
|
||||
- **[开发规范](references/development-standards.md)** - 完整的开发规范文档
|
||||
- **[API测试指南](references/api-testing-guide.md)** - 接口测试流程和脚本编写
|
||||
- **[数据表参考](references/database-tables.md)** - 常用MongoDB数据表结构和查询方法
|
||||
- **API文档模板**:`assets\估家科技开放接口文档-模版.docx`
|
||||
|
||||
---
|
||||
|
||||
## 常用工具类
|
||||
|
||||
详见项目根目录下的 `CLAUDE.md` 文件中的"常用工具类"章节。
|
||||
Binary file not shown.
@@ -0,0 +1,509 @@
|
||||
# API接口测试指南
|
||||
|
||||
接口开发完成后,需要进行系统化测试。本指南提供完整的测试流程和脚本组织方式。
|
||||
|
||||
## 测试脚本目录结构
|
||||
|
||||
在 `projects/fangjia-script/src/main/groovy/com/fangjia/script/` 下创建专门的测试包:
|
||||
|
||||
```
|
||||
opentest/ # 接口测试脚本专用包
|
||||
├── [InterfaceName]TestDataExtractor.groovy # 数据提取脚本
|
||||
├── [InterfaceName]InterfaceTest.groovy # 接口测试脚本
|
||||
└── data/ # 测试数据目录
|
||||
├── [interface]_test_data.xlsx # 测试数据(自动生成,单Sheet)
|
||||
└── [interface]_test_result.xlsx # 测试结果(自动生成,多Sheet)
|
||||
# - Sheet1: 测试结果(详细数据)
|
||||
# - Sheet2: 统计数据(汇总信息)
|
||||
```
|
||||
|
||||
**示例**:E基金地址匹配接口测试
|
||||
```
|
||||
opentest/
|
||||
├── EfundTestDataExtractor.groovy
|
||||
├── EfundInterfaceTest.groovy
|
||||
└── data/
|
||||
├── efund_test_data.xlsx # 测试数据
|
||||
└── efund_test_result.xlsx # 测试结果
|
||||
├── Sheet1: 测试结果 # 1000行详细数据
|
||||
└── Sheet2: 统计数据 # 汇总统计信息
|
||||
```
|
||||
|
||||
## 第一步:编写数据提取脚本
|
||||
|
||||
**目的**:从生产环境提取真实测试数据
|
||||
|
||||
**关键技术**:
|
||||
|
||||
### 1. 使用 Mongo3Utils 连接MongoDB(推荐)
|
||||
|
||||
```groovy
|
||||
import com.fangjia.core.Constants
|
||||
import com.fangjia.core.util.Mongo3Utils
|
||||
import com.mongodb.client.MongoCollection
|
||||
import org.bson.Document
|
||||
|
||||
// 连接206服务器
|
||||
MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
|
||||
Constants.SEAWATER_MONGO_URI, // 已配置好的连接URI
|
||||
"business", // 数据库
|
||||
"open_uri_log" // 集合
|
||||
)
|
||||
```
|
||||
|
||||
### 2. 使用 projection 优化查询
|
||||
|
||||
```groovy
|
||||
// 只查询需要的字段,减少网络传输
|
||||
Document query = new Document("user_id", "xxx")
|
||||
.append("request_uri", "/api/xxx")
|
||||
|
||||
Document projection = new Document("parameter_map", 1).append("_id", 0)
|
||||
|
||||
MongoCursor<Document> cursor = coll.find(query)
|
||||
.projection(projection) // 只返回 parameter_map
|
||||
.limit(1000)
|
||||
.iterator()
|
||||
```
|
||||
|
||||
### 3. 提取测试参数
|
||||
|
||||
```groovy
|
||||
List<List<Object>> excelData = []
|
||||
excelData << ["序号", "参数1", "参数2", "参数3"] // 表头
|
||||
|
||||
int index = 0
|
||||
while (cursor.hasNext()) {
|
||||
Document doc = cursor.next()
|
||||
Document paramMap = doc.get("parameter_map", Document.class)
|
||||
|
||||
String param1 = paramMap?.getString("param1") ?: ""
|
||||
String param2 = paramMap?.getString("param2") ?: ""
|
||||
|
||||
excelData << [++index, param1, param2]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 保存到Excel
|
||||
|
||||
```groovy
|
||||
import com.fangjia.script.util.ExcelUtils
|
||||
|
||||
// 自动确定脚本所在目录
|
||||
String scriptDir = new File(getClass().protectionDomain.codeSource.location.path).parent
|
||||
String dataDir = new File(scriptDir, "data").absolutePath
|
||||
new File(dataDir).mkdirs()
|
||||
|
||||
String outputFile = "${dataDir}${File.separator}test_data.xlsx"
|
||||
ExcelUtils.write(outputFile, excelData, "测试数据")
|
||||
```
|
||||
|
||||
## 第二步:编写接口测试脚本
|
||||
|
||||
**目的**:多线程调用接口,记录结果和性能指标
|
||||
|
||||
**推荐方法**:使用 `ExcelUtils.multiThreadingModify` 工具类(自动管理线程池和进度监控)
|
||||
|
||||
### 方法一:使用 ExcelUtils.multiThreadingModify(推荐)
|
||||
|
||||
**优势**:
|
||||
- ✅ 自动管理线程池(CPU核心数×4)
|
||||
- ✅ 自动处理线程安全
|
||||
- ✅ 自动进度监控(每1000条打印进度和百分比)
|
||||
- ✅ 代码简洁,专注业务逻辑
|
||||
- ✅ 超长等待时间(30天),适合大批量测试
|
||||
|
||||
**完整示例**:
|
||||
|
||||
```groovy
|
||||
import com.fangjia.core.util.HttpRequest
|
||||
import com.fangjia.script.util.ExcelUtils
|
||||
import net.sf.json.JSONObject
|
||||
|
||||
// 1. 准备测试数据和结果Excel
|
||||
String scriptDir = new File(getClass().protectionDomain.codeSource.location.path).parent
|
||||
String dataDir = new File(scriptDir, "data").absolutePath
|
||||
String inputFile = "${dataDir}${File.separator}test_data.xlsx"
|
||||
String outputFile = "${dataDir}${File.separator}test_result.xlsx"
|
||||
|
||||
// 2. 读取所有数据(包括表头)
|
||||
List<List<Object>> allData = ExcelUtils.read(inputFile, 0, 0)
|
||||
|
||||
// 3. 修改表头,添加结果列
|
||||
allData[0] = ["序号", "参数1", "参数2", "返回字段1", "返回字段2",
|
||||
"返回字段3", "耗时(ms)", "异常信息"]
|
||||
|
||||
// 4. 为每行数据添加空的结果列
|
||||
for (int i = 1; i < allData.size(); i++) {
|
||||
List row = allData[i]
|
||||
(3..7).each { row << "" } // 添加5个结果列
|
||||
}
|
||||
|
||||
// 5. 写入初始结果文件
|
||||
ExcelUtils.write(outputFile, allData, "测试结果")
|
||||
|
||||
// 6. 使用 multiThreadingModify 多线程调用接口
|
||||
ExcelUtils.multiThreadingModify(outputFile, { List row ->
|
||||
HttpRequest request = new HttpRequest()
|
||||
long startTime = System.currentTimeMillis()
|
||||
|
||||
try {
|
||||
// 提取参数(row[0]=序号, row[1]=参数1, row[2]=参数2)
|
||||
String param1 = row[1]?.toString() ?: ""
|
||||
String param2 = row[2]?.toString() ?: ""
|
||||
|
||||
// 调用接口
|
||||
Map<String, String> params = ["param1": param1, "param2": param2]
|
||||
String response = request.get("http://localhost:9180/api/xxx", params, "UTF-8")
|
||||
long duration = System.currentTimeMillis() - startTime
|
||||
|
||||
// 解析响应
|
||||
JSONObject json = JSONObject.fromObject(response)
|
||||
Integer code = json.optInt("code")
|
||||
JSONObject result = json.optJSONObject("result")
|
||||
|
||||
if (code == 200 && result != null) {
|
||||
// 成功:填充结果列(直接修改row,工具类自动处理线程安全)
|
||||
row[3] = result.optString("field1", "")
|
||||
row[4] = result.optString("field2", "")
|
||||
row[5] = result.optString("field3", "")
|
||||
row[6] = duration
|
||||
row[7] = "" // 无异常
|
||||
} else {
|
||||
// 失败:记录错误信息
|
||||
row[6] = duration
|
||||
row[7] = "接口返回错误(code=${code}): ${json.optString('msg', '')}"
|
||||
}
|
||||
|
||||
} catch (Exception e) {
|
||||
// 异常:记录异常信息
|
||||
long duration = System.currentTimeMillis() - startTime
|
||||
row[6] = duration
|
||||
row[7] = "异常: ${e.class.simpleName} - ${e.message}"
|
||||
}
|
||||
}, 0, "测试结果")
|
||||
|
||||
// 7. 读取结果并统计
|
||||
List<List<Object>> finalData = ExcelUtils.read(outputFile, 0, 0)
|
||||
int totalCount = finalData.size() - 1
|
||||
int successCount = 0
|
||||
int failCount = 0
|
||||
long totalTime = 0
|
||||
|
||||
// 耗时分布统计
|
||||
Map<String, Integer> timeDist = [
|
||||
"<100ms": 0,
|
||||
"100-200ms": 0,
|
||||
"200-500ms": 0,
|
||||
"500-1000ms": 0,
|
||||
">1000ms": 0
|
||||
]
|
||||
|
||||
for (int i = 1; i < finalData.size(); i++) {
|
||||
List row = finalData[i]
|
||||
String errorMsg = row[7]?.toString() ?: ""
|
||||
|
||||
if (errorMsg == "") {
|
||||
successCount++
|
||||
|
||||
// 统计耗时
|
||||
if (row[6] instanceof Number) {
|
||||
int duration = ((Number)row[6]).intValue()
|
||||
totalTime += duration
|
||||
|
||||
if (duration < 100) timeDist["<100ms"]++
|
||||
else if (duration < 200) timeDist["100-200ms"]++
|
||||
else if (duration < 500) timeDist["200-500ms"]++
|
||||
else if (duration < 1000) timeDist["500-1000ms"]++
|
||||
else timeDist[">1000ms"]++
|
||||
}
|
||||
} else {
|
||||
failCount++
|
||||
}
|
||||
}
|
||||
|
||||
// 8. 保存统计数据到新Sheet
|
||||
List<List<Object>> statsData = []
|
||||
statsData << ["统计项", "数值"]
|
||||
statsData << ["测试时间", new Date().format("yyyy-MM-dd HH:mm:ss")]
|
||||
statsData << ["", ""]
|
||||
statsData << ["总测试数", totalCount]
|
||||
statsData << ["成功数", successCount]
|
||||
statsData << ["失败数", failCount]
|
||||
statsData << ["成功率", totalCount > 0 ? String.format('%.2f%%', successCount * 100.0 / totalCount) : '0.00%']
|
||||
|
||||
if (successCount > 0) {
|
||||
int avgTime = (totalTime / successCount).intValue()
|
||||
statsData << ["", ""]
|
||||
statsData << ["平均耗时(ms)", avgTime]
|
||||
|
||||
// 耗时分布
|
||||
statsData << ["", ""]
|
||||
statsData << ["耗时分布", "数量"]
|
||||
timeDist.each { range, count ->
|
||||
statsData << [range, count]
|
||||
}
|
||||
}
|
||||
|
||||
// 添加统计Sheet
|
||||
ExcelUtils.write(outputFile, statsData, "统计数据")
|
||||
|
||||
// 9. 控制台输出统计结果
|
||||
println "\n========== 测试完成 =========="
|
||||
println "总测试数:${totalCount}"
|
||||
println "成功数:${successCount}"
|
||||
println "失败数:${failCount}"
|
||||
println "成功率:${totalCount > 0 ? String.format('%.2f%%', successCount * 100.0 / totalCount) : '0.00%'}"
|
||||
|
||||
if (successCount > 0) {
|
||||
int avgTime = (totalTime / successCount).intValue()
|
||||
println "平均耗时:${avgTime} ms"
|
||||
|
||||
println "\n耗时分布:"
|
||||
timeDist.each { range, count ->
|
||||
if (count > 0) {
|
||||
println " ${range}: ${count} 条"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
println "\n结果文件:${outputFile}"
|
||||
println " - Sheet1: 测试结果(详细数据)"
|
||||
println " - Sheet2: 统计数据(汇总信息)"
|
||||
```
|
||||
|
||||
### 方法二:手动管理线程池(适合需要自定义控制的场景)
|
||||
|
||||
<details>
|
||||
<summary>点击展开手动管理线程池的示例代码</summary>
|
||||
|
||||
```groovy
|
||||
import java.util.concurrent.*
|
||||
import java.util.concurrent.atomic.AtomicInteger
|
||||
import com.fangjia.core.util.HttpRequest
|
||||
import net.sf.json.JSONObject
|
||||
|
||||
// 1. 读取测试数据
|
||||
List<List<Object>> testData = ExcelUtils.read(inputFile, 0, 1) // 跳过表头
|
||||
|
||||
// 2. 准备结果数据
|
||||
List<List<Object>> resultData = []
|
||||
resultData << ["序号", "参数1", "参数2", "返回字段1", "返回字段2", "耗时(ms)", "异常信息"]
|
||||
testData.each { row ->
|
||||
List newRow = [row[0], row[1], row[2]]
|
||||
(3..6).each { newRow << "" }
|
||||
resultData << newRow
|
||||
}
|
||||
|
||||
// 3. 配置线程池
|
||||
int nThread = Runtime.getRuntime().availableProcessors() * 4
|
||||
ExecutorService executorService = Executors.newFixedThreadPool(nThread)
|
||||
AtomicInteger counter = new AtomicInteger(0)
|
||||
AtomicInteger successCounter = new AtomicInteger(0)
|
||||
|
||||
// 4. 提交任务
|
||||
testData.eachWithIndex { List testRow, int i ->
|
||||
final int rowIndex = i + 1
|
||||
executorService.submit({
|
||||
HttpRequest request = new HttpRequest()
|
||||
long startTime = System.currentTimeMillis()
|
||||
|
||||
try {
|
||||
String param1 = testRow[1]?.toString() ?: ""
|
||||
String response = request.get("http://localhost:9180/api/xxx",
|
||||
["param1": param1], "UTF-8")
|
||||
long duration = System.currentTimeMillis() - startTime
|
||||
|
||||
JSONObject json = JSONObject.fromObject(response)
|
||||
JSONObject result = json.optJSONObject("result")
|
||||
|
||||
synchronized(resultData) {
|
||||
if (json.optInt("code") == 200 && result != null) {
|
||||
resultData[rowIndex][3] = result.optString("field1", "")
|
||||
resultData[rowIndex][4] = result.optString("field2", "")
|
||||
resultData[rowIndex][5] = duration
|
||||
successCounter.incrementAndGet()
|
||||
} else {
|
||||
resultData[rowIndex][5] = duration
|
||||
resultData[rowIndex][6] = "错误: ${json.optString('msg')}"
|
||||
}
|
||||
}
|
||||
} catch (Exception e) {
|
||||
synchronized(resultData) {
|
||||
resultData[rowIndex][6] = "异常: ${e.message}"
|
||||
}
|
||||
}
|
||||
|
||||
if (counter.incrementAndGet() % 100 == 0) {
|
||||
println "进度: ${counter.get()}/${testData.size()}"
|
||||
}
|
||||
} as Runnable)
|
||||
}
|
||||
|
||||
// 5. 等待完成并保存结果
|
||||
executorService.shutdown()
|
||||
executorService.awaitTermination(30, TimeUnit.MINUTES)
|
||||
ExcelUtils.write(outputFile, resultData, "测试结果")
|
||||
```
|
||||
</details>
|
||||
|
||||
## 第三步:运行测试流程
|
||||
|
||||
### 1. 构建项目
|
||||
```bash
|
||||
cd deliverables/script
|
||||
mvn clean package -Dmaven.test.skip=true
|
||||
```
|
||||
|
||||
### 2. 提取测试数据
|
||||
```bash
|
||||
groovy -cp "target/classes;target/classes/lib/*" \
|
||||
projects/fangjia-script/src/main/groovy/com/fangjia/script/opentest/XXXTestDataExtractor.groovy
|
||||
```
|
||||
|
||||
### 3. 启动fangjia-open服务
|
||||
```bash
|
||||
cd deliverables/fangjiaopen
|
||||
mvn tomcat7:run
|
||||
```
|
||||
|
||||
### 4. 运行接口测试
|
||||
```bash
|
||||
groovy -cp "target/classes;target/classes/lib/*" \
|
||||
projects/fangjia-script/src/main/groovy/com/fangjia/script/opentest/XXXInterfaceTest.groovy
|
||||
```
|
||||
|
||||
## Excel结果文件结构
|
||||
|
||||
### 测试数据Excel(单Sheet)
|
||||
|
||||
| 列 | 字段 | 说明 |
|
||||
|----|------|------|
|
||||
| A | 序号 | 1-N |
|
||||
| B | 参数1 | 接口输入参数 |
|
||||
| C | 参数2 | 接口输入参数 |
|
||||
| ... | ... | 更多参数 |
|
||||
|
||||
### 测试结果Excel(多Sheet)
|
||||
|
||||
#### 📄 Sheet1: 测试结果(详细数据)
|
||||
|
||||
| 列 | 字段 | 说明 |
|
||||
|----|------|------|
|
||||
| A | 序号 | 同测试数据 |
|
||||
| B | 参数1 | 同测试数据 |
|
||||
| C | 参数2 | 同测试数据 |
|
||||
| D | 返回字段1 | 接口返回结果 |
|
||||
| E | 返回字段2 | 接口返回结果 |
|
||||
| ... | ... | 更多返回字段 |
|
||||
| N | 耗时(ms) | 接口调用耗时 |
|
||||
| N+1 | 异常信息 | 错误时记录 |
|
||||
|
||||
#### 📊 Sheet2: 统计数据(汇总信息)
|
||||
|
||||
| 列 | 字段 | 说明 |
|
||||
|----|------|------|
|
||||
| A | 统计项 | 统计项名称 |
|
||||
| B | 数值 | 统计值 |
|
||||
|
||||
统计内容包括:
|
||||
- 测试时间(测试执行的时间戳)
|
||||
- 总测试数、成功数、失败数、成功率
|
||||
- 平均耗时(仅统计成功的请求)
|
||||
- 耗时分布(<100ms、100-200ms、200-500ms、500-1000ms、>1000ms)
|
||||
|
||||
示例:
|
||||
```
|
||||
| 统计项 | 数值 |
|
||||
|----------------|----------------------|
|
||||
| 测试时间 | 2026-02-26 14:30:15 |
|
||||
| | |
|
||||
| 总测试数 | 1000 |
|
||||
| 成功数 | 980 |
|
||||
| 失败数 | 20 |
|
||||
| 成功率 | 98.00% |
|
||||
| | |
|
||||
| 平均耗时(ms) | 245 |
|
||||
| | |
|
||||
| 耗时分布 | 数量 |
|
||||
| <100ms | 120 |
|
||||
| 100-200ms | 350 |
|
||||
| 200-500ms | 480 |
|
||||
| 500-1000ms | 30 |
|
||||
| >1000ms | 0 |
|
||||
```
|
||||
|
||||
## 测试脚本最佳实践
|
||||
|
||||
### ✅ 推荐做法
|
||||
|
||||
1. **MongoDB查询优化**
|
||||
- 使用 `Mongo3Utils` 而非旧版 `MongoUtils`
|
||||
- 使用 `projection` 只查询需要的字段
|
||||
- 使用 `Constants` 中的预定义URI
|
||||
|
||||
2. **路径处理**
|
||||
- 使用相对路径而非硬编码
|
||||
- 脚本自动识别所在目录:`new File(getClass().protectionDomain.codeSource.location.path).parent`
|
||||
|
||||
3. **多线程测试(强烈推荐)**
|
||||
- **优先使用** `ExcelUtils.multiThreadingModify` 工具方法
|
||||
- 自动管理线程池(CPU核心数×4)
|
||||
- 自动处理线程安全(无需手动 synchronized)
|
||||
- 自动进度监控(每1000条打印进度和百分比)
|
||||
- 代码简洁,专注业务逻辑
|
||||
|
||||
4. **进度监控**
|
||||
- 使用工具类自动监控(推荐)
|
||||
- 或手动实现:每100条打印进度,包含时间戳
|
||||
|
||||
5. **异常处理**
|
||||
- 捕获所有异常
|
||||
- 记录到Excel而非终止程序
|
||||
- 异常信息包含类型和消息
|
||||
|
||||
6. **统计数据保存**
|
||||
- 使用 `ExcelUtils.write(outputFile, statsData, "统计数据")` 创建统计Sheet
|
||||
- 统计内容包括:测试时间、成功率、平均耗时、耗时分布
|
||||
- 方便后续分析和生成测试报告
|
||||
|
||||
### ❌ 避免做法
|
||||
|
||||
1. ❌ 硬编码文件路径(如 `D:\test\data.xlsx`)
|
||||
2. ❌ 查询所有字段而不使用 projection
|
||||
3. ❌ 使用旧版 MongoDB API(`DBObject`、`BasicDBObject`)
|
||||
4. ❌ 单线程测试大量数据
|
||||
5. ❌ 异常时终止整个测试
|
||||
6. ❌ 手动管理线程池(除非有特殊需求,否则用工具类)
|
||||
7. ❌ 忘记处理线程安全问题(使用工具类可避免)
|
||||
|
||||
## 测试完成后的分析
|
||||
|
||||
测试完成后,Excel文件包含两个Sheet,便于多维度分析:
|
||||
|
||||
### 📊 使用统计数据Sheet快速分析
|
||||
|
||||
1. **成功率分析**:查看成功率是否 >95%
|
||||
- 低于95%需要排查失败原因
|
||||
- 在"测试结果"Sheet中过滤"异常信息"列查看失败详情
|
||||
|
||||
2. **性能分析**:查看平均耗时和耗时分布
|
||||
- 平均耗时应 <500ms(根据业务要求调整)
|
||||
- 耗时分布帮助识别性能瓶颈
|
||||
- 如果 >1000ms 的数量较多,需优化接口性能
|
||||
|
||||
3. **异常分析**:在"测试结果"Sheet中
|
||||
- 使用Excel筛选功能查看所有失败记录
|
||||
- 统计异常类型(如超时、参数错误、业务异常等)
|
||||
- 针对高频异常进行优化
|
||||
|
||||
4. **数据质量分析**:在"测试结果"Sheet中
|
||||
- 检查返回字段的完整性(是否有大量空值)
|
||||
- 检查价格、匹配级别等核心字段的填充率
|
||||
- 对比不同匹配级别的数据分布
|
||||
|
||||
### 💡 建议
|
||||
|
||||
- 将统计数据Sheet制作成Excel图表(饼图、柱状图)便于可视化分析
|
||||
- 保存多次测试结果,对比性能变化趋势
|
||||
- 将测试报告作为接口验收的依据
|
||||
@@ -0,0 +1,201 @@
|
||||
# OpenAPI 接口开发代码模板
|
||||
|
||||
## Controller 模板
|
||||
|
||||
```java
|
||||
package com.fangjia.open.controllers;
|
||||
|
||||
import com.fangjia.open.model.*;
|
||||
import com.fangjia.service.{业务模块}.{Service名称};
|
||||
import com.fangjia.open.interceptors.Authority;
|
||||
import com.fangjia.open.interceptors.Role;
|
||||
import org.apache.commons.lang.StringUtils;
|
||||
|
||||
@Authority(role = Role.USER)
|
||||
public class {Controller名称}Controller {
|
||||
|
||||
private {Service名称} {service实例名};
|
||||
|
||||
// Spring依赖注入(约定大于配置)
|
||||
public void set{Service名称}({Service名称} {service实例名}) {
|
||||
this.{service实例名} = {service实例名};
|
||||
}
|
||||
|
||||
/**
|
||||
* {接口功能描述}
|
||||
* URL: /{controller路径}/{方法名}
|
||||
*/
|
||||
@Authority(role = Role.USER)
|
||||
public Object {方法名}Action({Model名称} model) {
|
||||
RestfulModelAndView mav = new RestfulModelAndView();
|
||||
|
||||
// 参数校验
|
||||
if (StringUtils.isBlank(model.get{必填字段}())) {
|
||||
mav.setModel(BasicModel.buildBadRequestModel("{字段}不能为空"));
|
||||
return mav;
|
||||
}
|
||||
|
||||
// 调用Service
|
||||
{Result类型} result = {service实例名}.{service方法}(model);
|
||||
|
||||
// 封装返回结果
|
||||
if (result != null) {
|
||||
// 情况1: 有专用DTO类
|
||||
mav.setModel(BasicModel.buildOKModel().setResult(result));
|
||||
|
||||
// 情况2: 使用UniversalDto
|
||||
// UniversalDto dto = UniversalDto.newDto();
|
||||
// dto.append("fieldName1", result.getValue1());
|
||||
// dto.append("fieldName2", result.getValue2());
|
||||
// mav.setModel(BasicModel.buildOKModel().setResult(dto));
|
||||
} else {
|
||||
mav.setModel(BasicModel.buildBadRequestModel("未找到数据"));
|
||||
}
|
||||
|
||||
return mav;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Service 接口模板
|
||||
|
||||
```java
|
||||
package com.fangjia.service.{业务模块};
|
||||
|
||||
import com.fangjia.open.model.{Model名称};
|
||||
import {Result类的包路径}.{Result类名};
|
||||
|
||||
/**
|
||||
* {Service功能描述}
|
||||
*/
|
||||
public interface {Service名称} {
|
||||
|
||||
/**
|
||||
* {方法功能描述}
|
||||
* @param model 输入参数
|
||||
* @return {返回值描述}
|
||||
*/
|
||||
{Result类型} {方法名}({Model名称} model);
|
||||
}
|
||||
```
|
||||
|
||||
## Service 实现类模板
|
||||
|
||||
```java
|
||||
package com.fangjia.service.{业务模块};
|
||||
|
||||
import com.fangjia.dal.{DAO包路径}.{DAO名称};
|
||||
import com.fangjia.open.model.{Model名称};
|
||||
import {Result类的包路径}.{Result类名};
|
||||
|
||||
/**
|
||||
* {Service功能描述}实现类
|
||||
*/
|
||||
public class {Service名称}Impl implements {Service名称} {
|
||||
|
||||
private {DAO名称} {dao实例名};
|
||||
|
||||
// Spring依赖注入
|
||||
public void set{DAO名称}({DAO名称} {dao实例名}) {
|
||||
this.{dao实例名} = {dao实例名};
|
||||
}
|
||||
|
||||
@Override
|
||||
public {Result类型} {方法名}({Model名称} model) {
|
||||
// 业务逻辑实现
|
||||
// 示例:从DAO查询数据
|
||||
{Result类型} result = {dao实例名}.findBy{查询条件}(
|
||||
model.get{字段1}(),
|
||||
model.get{字段2}()
|
||||
);
|
||||
|
||||
// 数据处理
|
||||
if (result != null) {
|
||||
// 可以进行额外的业务处理
|
||||
// result.setXxx(...);
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Model 类模板
|
||||
|
||||
```java
|
||||
package com.fangjia.open.model;
|
||||
|
||||
/**
|
||||
* {接口名称}输入参数Model
|
||||
*/
|
||||
public class {Model名称} {
|
||||
|
||||
private String {字段1};
|
||||
private String {字段2};
|
||||
private Integer {字段3};
|
||||
// ... 其他字段
|
||||
|
||||
// Getter和Setter方法
|
||||
public String get{字段1}() {
|
||||
return {字段1};
|
||||
}
|
||||
|
||||
public void set{字段1}(String {字段1}) {
|
||||
this.{字段1} = {字段1};
|
||||
}
|
||||
|
||||
public String get{字段2}() {
|
||||
return {字段2};
|
||||
}
|
||||
|
||||
public void set{字段2}(String {字段2}) {
|
||||
this.{字段2} = {字段2};
|
||||
}
|
||||
|
||||
public Integer get{字段3}() {
|
||||
return {字段3};
|
||||
}
|
||||
|
||||
public void set{字段3}(Integer {字段3}) {
|
||||
this.{字段3} = {字段3};
|
||||
}
|
||||
|
||||
// ... 其他getter/setter
|
||||
}
|
||||
```
|
||||
|
||||
## 使用 UniversalDto 封装示例
|
||||
|
||||
```java
|
||||
// 当没有专用的Result DTO类时,使用UniversalDto
|
||||
UniversalDto dto = UniversalDto.newDto();
|
||||
dto.append("communityName", "陆家嘴花园");
|
||||
dto.append("city", "上海市");
|
||||
dto.append("district", "浦东新区");
|
||||
dto.append("referencePrice", 126000);
|
||||
dto.append("updateTime", "2026-01-31");
|
||||
|
||||
mav.setModel(BasicModel.buildOKModel().setResult(dto));
|
||||
```
|
||||
|
||||
## 常见返回格式
|
||||
|
||||
```java
|
||||
// 成功返回(有数据)
|
||||
mav.setModel(BasicModel.buildOKModel().setResult(result));
|
||||
|
||||
// 成功返回(无数据)
|
||||
mav.setModel(BasicModel.buildOKModel());
|
||||
|
||||
// 参数错误
|
||||
mav.setModel(BasicModel.buildBadRequestModel("参数错误信息"));
|
||||
|
||||
// 未授权
|
||||
mav.setModel(BasicModel.buildUnAuthorizedModel());
|
||||
|
||||
// 服务器错误
|
||||
mav.setModel(BasicModel.buildServerErrorModel());
|
||||
|
||||
// 自定义错误码
|
||||
mav.setModel(BasicModel.buildModel(错误码, "错误信息"));
|
||||
```
|
||||
@@ -0,0 +1,304 @@
|
||||
# 常用数据表参考
|
||||
|
||||
本文档记录开发OpenAPI接口时常用的数据表结构和用途,便于快速查询和复用。
|
||||
|
||||
## 数据库命名规范
|
||||
|
||||
### @Table 注解格式
|
||||
|
||||
在 `fangjia-dal` 的实体类中,MongoDB 集合通过 JPA 的 `@Table` 注解来指定:
|
||||
|
||||
```java
|
||||
@Entity
|
||||
@Table(name = "database.collection")
|
||||
public class YourEntity implements MongoEntity {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**重要规则**:
|
||||
- **点之前**(`.`前):**数据库名**(database)
|
||||
- **点之后**(`.`后):**集合名**(collection)
|
||||
- 不同的数据库对应不同的 MongoDB URI 常量
|
||||
|
||||
### 数据库与 URI 常量的对应关系
|
||||
|
||||
| 数据库名 | MongoDB URI 常量 | 服务器地址 | 用途 |
|
||||
|---------|-----------------|-----------|------|
|
||||
| `business` | `Constants.SEAWATER_MONGO_URI` | 192.168.0.206:27020 | 业务日志、开放平台相关 |
|
||||
| `fangjia` | `Constants.FANGJIA_MONGO_URI` | mongo.db.fangjia.com:28017 | 核心业务数据 |
|
||||
| `fangjia_stat` | `Constants.FANGJIA_MONGO_URI` | mongo.db.fangjia.com:28017 | 统计数据 |
|
||||
| `address_analytics` | `Constants.FANGJIA_MONGO_URI` | mongo.db.fangjia.com:28017 | 地址分析数据 |
|
||||
|
||||
**示例**:
|
||||
```java
|
||||
// business.open_uri_log → business 数据库 → 使用 SEAWATER_MONGO_URI
|
||||
@Table(name = "business.open_uri_log")
|
||||
|
||||
// fangjia_stat.district_stat → fangjia_stat 数据库 → 使用 FANGJIA_MONGO_URI
|
||||
@Table(name = "fangjia_stat.district_stat")
|
||||
|
||||
// fangjia.seaweed → fangjia 数据库,seaweed 集合 → 使用 FANGJIA_MONGO_URI
|
||||
@Table(name = "fangjia.seaweed")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MongoDB数据表
|
||||
|
||||
### 1. business.open_uri_log
|
||||
|
||||
**服务器**:192.168.0.206 (通过 `Constants.SEAWATER_MONGO_URI` 连接)
|
||||
|
||||
**作用**:记录所有开放平台API的调用日志,包含请求参数、返回结果等
|
||||
|
||||
**常用字段**:
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|-------|------|------|
|
||||
| `user_id` | String | 调用用户ID |
|
||||
| `request_uri` | String | 请求的API路径(如 `/address/risk`) |
|
||||
| `parameter_map` | Document | 请求参数(嵌套文档) |
|
||||
| `res_map` | Document | 返回结果(嵌套文档) |
|
||||
| `c_date` | Date | 创建时间 |
|
||||
|
||||
**连接方式**:
|
||||
```groovy
|
||||
import com.fangjia.core.Constants
|
||||
import com.fangjia.core.util.Mongo3Utils
|
||||
|
||||
MongoCollection<Document> coll = Mongo3Utils.getDbCollection(
|
||||
Constants.SEAWATER_MONGO_URI,
|
||||
"business",
|
||||
"open_uri_log"
|
||||
)
|
||||
```
|
||||
|
||||
**典型查询**:
|
||||
```groovy
|
||||
// 查询特定用户的API调用记录
|
||||
Document query = new Document("user_id", "1007569")
|
||||
.append("request_uri", "/address/risk")
|
||||
|
||||
// 使用projection优化查询
|
||||
Document projection = new Document("parameter_map", 1).append("_id", 0)
|
||||
MongoCursor<Document> cursor = coll.find(query)
|
||||
.projection(projection)
|
||||
.limit(1000)
|
||||
.iterator()
|
||||
```
|
||||
|
||||
**使用场景**:
|
||||
- 提取历史调用数据用于接口测试
|
||||
- 分析API调用量和参数分布
|
||||
- 排查接口调用问题
|
||||
|
||||
---
|
||||
|
||||
### 2. fangjia_stat.district_stat
|
||||
|
||||
**数据库**:fangjia_stat (通过 `Constants.FANGJIA_MONGO_URI` 连接)
|
||||
**集合名**:district_stat
|
||||
|
||||
**作用**:存储小区级别的价格统计数据
|
||||
|
||||
**常用字段**:
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|-------|------|------|
|
||||
| `city` | String | 城市 |
|
||||
| `region` | String | 区域 |
|
||||
| `name` | String | 小区名称 |
|
||||
| `avg_price_2b` | Integer | 均价(优先使用,元/平米) |
|
||||
| `avgPrice` | Integer | 均价(备选,元/平米) |
|
||||
| `weekend` | Date | 数据更新时间 |
|
||||
|
||||
**典型查询**:
|
||||
```groovy
|
||||
// 通过DistrictStatService查询
|
||||
DistrictStat latestStat = districtStatService.findOneDistrictStatsSort(
|
||||
city, region, name, null
|
||||
)
|
||||
|
||||
// 优先使用avg_price_2b
|
||||
Integer avgPrice = null
|
||||
if (latestStat.getAvg_price_2b() != null && latestStat.getAvg_price_2b() > 0) {
|
||||
avgPrice = latestStat.getAvg_price_2b()
|
||||
} else if (latestStat.getAvgPrice() > 0) {
|
||||
avgPrice = latestStat.getAvgPrice()
|
||||
}
|
||||
```
|
||||
|
||||
**使用场景**:
|
||||
- 查询小区参考均价
|
||||
- E基金地址匹配接口返回参考价格
|
||||
- 房价评估相关接口
|
||||
|
||||
---
|
||||
|
||||
### 3. fangjia.deal_price
|
||||
|
||||
**数据库**:fangjia (通过 `Constants.FANGJIA_MONGO_URI` 连接)
|
||||
**集合名**:deal_price
|
||||
|
||||
**作用**:存储房产成交记录
|
||||
|
||||
**常用字段**:
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|-------|------|------|
|
||||
| `city` | String | 城市 |
|
||||
| `region` | String | 区域 |
|
||||
| `name` | String | 小区名称 |
|
||||
| `avgPrice` | Integer | 成交单价(元/平米) |
|
||||
| `totalPrice` | Integer | 成交总价(万元) |
|
||||
| 成交时间 | Date | 成交日期 |
|
||||
|
||||
**典型查询**:
|
||||
```groovy
|
||||
// 通过DealPriceService查询近半年成交记录
|
||||
Date halfYearAgo = new Date(System.currentTimeMillis() - 180L * 24 * 60 * 60 * 1000)
|
||||
Date now = new Date()
|
||||
|
||||
List<DealPrice> dealPrices = dealPriceService.findDealPriceList(
|
||||
city, region, name, halfYearAgo, now
|
||||
)
|
||||
|
||||
// 找到单价最接近参考均价的成交记录
|
||||
DealPrice closestDeal = null
|
||||
int minDiff = Integer.MAX_VALUE
|
||||
for (DealPrice deal : dealPrices) {
|
||||
if (deal.getAvgPrice() != null && deal.getTotalPrice() != null) {
|
||||
int diff = Math.abs(deal.getAvgPrice() - referencePrice)
|
||||
if (diff < minDiff) {
|
||||
minDiff = diff
|
||||
closestDeal = deal
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**使用场景**:
|
||||
- 查询成交记录
|
||||
- 计算典型总价(最接近参考均价的成交总价)
|
||||
- 成交数据分析
|
||||
|
||||
---
|
||||
|
||||
### 4. fangjia_stat.region_sell_stat
|
||||
|
||||
**数据库**:fangjia_stat (通过 `Constants.FANGJIA_MONGO_URI` 连接)
|
||||
**集合名**:region_sell_stat
|
||||
|
||||
**作用**:存储区域级别的销售价格统计
|
||||
|
||||
**常用字段**:
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|-------|------|------|
|
||||
| `city` | String | 城市(简称格式) |
|
||||
| `region` | String | 区域(简称格式) |
|
||||
| `avgPrice` | Integer | 区域均价(元/平米) |
|
||||
| `date` | Integer | 数据日期(yyyyMM格式) |
|
||||
| `updateDate` | Date | 更新时间 |
|
||||
|
||||
**典型查询**:
|
||||
```groovy
|
||||
// 需要先格式化城市和区域为简称
|
||||
String formattedCity = RegionData.formatCity(city)
|
||||
String formattedRegion = RegionData.formatRegion(formattedCity, district)
|
||||
|
||||
// 通过RegionSellStatService查询最新区域价格
|
||||
RegionSellStat regionSellStat = regionSellStatService.findNewestRegionPrice(
|
||||
formattedCity, formattedRegion
|
||||
)
|
||||
|
||||
if (regionSellStat != null && regionSellStat.getAvgPrice() != null) {
|
||||
Integer avgPrice = regionSellStat.getAvgPrice()
|
||||
// 格式化日期
|
||||
String updateTime = DateUtil.formatByPattern(
|
||||
DateUtil.parseDate(regionSellStat.getDate().toString(), "yyyyMM"),
|
||||
"yyyy-MM-dd"
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**使用场景**:
|
||||
- 查询区域级别参考价格
|
||||
- 地址匹配失败时返回区域价格
|
||||
- 区域价格趋势分析
|
||||
|
||||
---
|
||||
|
||||
### 5. fangjia.seaweed
|
||||
|
||||
**数据库**:fangjia (通过 `Constants.FANGJIA_MONGO_URI` 连接)
|
||||
**集合名**:seaweed (实体类为 District,通过 @DatastoreCategory("district") 标识)
|
||||
|
||||
**作用**:存储小区、写字楼等建筑的基础信息(权威数据源)
|
||||
|
||||
**常用字段**:
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|-------|------|------|
|
||||
| `_id` | ObjectId | 小区唯一标识 |
|
||||
| `city` | String | 城市 |
|
||||
| `region` | String | 区域 |
|
||||
| `name` | String | 小区/建筑名称 |
|
||||
| `cat` | String | 分类(district=小区, office=写字楼) |
|
||||
| `estate_type2` | String | 物业类型 |
|
||||
|
||||
**典型查询**:
|
||||
```groovy
|
||||
// 通过DistrictService根据ID查询
|
||||
District district = districtService.findById(id)
|
||||
|
||||
if (district != null) {
|
||||
String city = district.getCity()
|
||||
String region = district.getRegion()
|
||||
String name = district.getName()
|
||||
}
|
||||
```
|
||||
|
||||
**使用场景**:
|
||||
- 根据ID查询小区权威信息
|
||||
- 获取小区的城市、区域、名称用于后续查询
|
||||
- 验证POI信息的准确性
|
||||
|
||||
---
|
||||
|
||||
## 如何记录新数据表
|
||||
|
||||
**遇到新数据表时,请主动询问用户是否需要记录,格式如下:**
|
||||
|
||||
> 我在开发过程中用到了数据表 `XXX.YYY`,是否需要记录到技能文档中供以后复用?
|
||||
>
|
||||
> 如果需要,请告诉我:
|
||||
> 1. 这个表的主要作用
|
||||
> 2. 常用的查询场景
|
||||
> 3. 是否有特殊的查询方式或注意事项
|
||||
|
||||
**记录模板**:
|
||||
|
||||
```markdown
|
||||
### N. database.table_name
|
||||
|
||||
**服务器/数据库**:服务器地址或数据库类型
|
||||
|
||||
**作用**:简要说明表的用途
|
||||
|
||||
**常用字段**:
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|-------|------|------|
|
||||
| `field1` | Type | 说明 |
|
||||
| `field2` | Type | 说明 |
|
||||
|
||||
**连接方式**:(如果有特殊连接方式)
|
||||
```groovy
|
||||
// 代码示例
|
||||
```
|
||||
|
||||
**典型查询**:
|
||||
```groovy
|
||||
// 常用查询示例
|
||||
```
|
||||
|
||||
**使用场景**:
|
||||
- 场景1
|
||||
- 场景2
|
||||
```
|
||||
@@ -0,0 +1,190 @@
|
||||
# OpenAPI 开发规范
|
||||
|
||||
## 项目结构
|
||||
|
||||
### Controller层
|
||||
- **位置**: `projects/fangjia-open/src/main/java/com/fangjia/open/controllers/`
|
||||
- **命名**: `{业务名}Controller.java`
|
||||
- **方法命名**: `{方法名}Action`
|
||||
- **URL映射**: `/{controller路径}/{方法名}`
|
||||
- 示例: `PropertyController.priceQueryAction` → `/property/priceQuery`
|
||||
|
||||
### Service层
|
||||
- **位置**: `projects/fangjia-service/src/main/java/com/fangjia/service/{业务模块}/`
|
||||
- **命名**:
|
||||
- 接口: `{Service名}.java`
|
||||
- 实现: `{Service名}Impl.java`
|
||||
- **结构**: 必须有接口 + 实现类
|
||||
|
||||
### Model层
|
||||
- **位置**: `projects/fangjia-open/src/main/java/com/fangjia/open/model/`
|
||||
- **命名**: `{功能名}Model.java`
|
||||
- **内容**: 输入参数的POJO类,包含getter/setter方法
|
||||
|
||||
### DAO层
|
||||
- **位置**: `projects/fangjia-dal/src/main/java/com/fangjia/dal/`
|
||||
- **原则**: 优先使用已有DAO,需要时再新建
|
||||
- **基类**:
|
||||
- MongoDB: `AbstractMongoDao`
|
||||
- MySQL: `AbstractSqlDao`
|
||||
- JPA: `AbstractJpaCompatibleDao`
|
||||
|
||||
## 依赖注入规范
|
||||
|
||||
### 约定大于配置
|
||||
- **不需要**使用注解(@Service, @Autowired等)
|
||||
- **不需要**手动配置Spring Bean XML
|
||||
- **只需要**提供setter方法,Spring会自动注入
|
||||
|
||||
### 示例
|
||||
|
||||
```java
|
||||
public class PropertyController {
|
||||
private PropertyService propertyService;
|
||||
|
||||
// 提供setter方法即可,无需注解
|
||||
public void setPropertyService(PropertyService propertyService) {
|
||||
this.propertyService = propertyService;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 参数校验
|
||||
|
||||
### 手动代码校验
|
||||
- 使用 `StringUtils.isBlank()` 检查字符串
|
||||
- 使用 `if` 语句进行逻辑判断
|
||||
- **不使用** `@Valid` 注解或 JSR303 校验
|
||||
|
||||
### 示例
|
||||
|
||||
```java
|
||||
// 必填参数校验
|
||||
if (StringUtils.isBlank(model.getCity())) {
|
||||
mav.setModel(BasicModel.buildBadRequestModel("城市不能为空"));
|
||||
return mav;
|
||||
}
|
||||
|
||||
// 数值范围校验
|
||||
if (model.getSize() != null && model.getSize() <= 0) {
|
||||
mav.setModel(BasicModel.buildBadRequestModel("面积必须大于0"));
|
||||
return mav;
|
||||
}
|
||||
```
|
||||
|
||||
## 异常处理
|
||||
|
||||
### 统一异常处理
|
||||
- **不需要**手动 try-catch
|
||||
- 框架已有统一异常处理机制
|
||||
- 直接调用Service方法即可
|
||||
|
||||
```java
|
||||
// 正确 - 不需要try-catch
|
||||
PropertyResult result = propertyService.queryPrice(model);
|
||||
|
||||
// 错误 - 不要这样写
|
||||
// try {
|
||||
// PropertyResult result = propertyService.queryPrice(model);
|
||||
// } catch (Exception e) {
|
||||
// ...
|
||||
// }
|
||||
```
|
||||
|
||||
## 返回值规范
|
||||
|
||||
### 统一返回格式
|
||||
|
||||
所有接口返回 `RestfulModelAndView` 对象:
|
||||
|
||||
```java
|
||||
RestfulModelAndView mav = new RestfulModelAndView();
|
||||
```
|
||||
|
||||
### 设置返回内容
|
||||
|
||||
使用 `BasicModel` 构建返回对象:
|
||||
|
||||
```java
|
||||
// 成功 - 返回数据
|
||||
mav.setModel(BasicModel.buildOKModel().setResult(data));
|
||||
|
||||
// 成功 - 无数据
|
||||
mav.setModel(BasicModel.buildOKModel());
|
||||
|
||||
// 失败 - 参数错误
|
||||
mav.setModel(BasicModel.buildBadRequestModel("错误描述"));
|
||||
```
|
||||
|
||||
### JSON格式
|
||||
|
||||
返回的JSON格式:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "ok",
|
||||
"result": {
|
||||
// 实际数据
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 编码规范
|
||||
|
||||
| 项目 | 规范 |
|
||||
|-----|------|
|
||||
| **字符编码** | UTF-8 |
|
||||
| **命名风格** | 驼峰命名法(camelCase) |
|
||||
| **参数大小写** | 大小写敏感 |
|
||||
| **URL大小写** | 大小写敏感 |
|
||||
|
||||
## 认证授权
|
||||
|
||||
### Token认证
|
||||
- 所有接口方法需要添加 `@Authority(role = Role.USER)`
|
||||
- 调用时必须传递 `token` 参数
|
||||
- Token有效期:2小时
|
||||
|
||||
```java
|
||||
@Authority(role = Role.USER)
|
||||
public class PropertyController {
|
||||
|
||||
@Authority(role = Role.USER)
|
||||
public Object priceQueryAction(PropertyQueryModel model) {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 本地测试(可选)
|
||||
|
||||
```bash
|
||||
cd deliverables/fangjiaopen
|
||||
mvn tomcat7:run
|
||||
```
|
||||
|
||||
访问地址:`http://localhost:8032/{controller}/{action}?param1=value1&token=xxx`
|
||||
|
||||
## 构建打包
|
||||
|
||||
```bash
|
||||
cd deliverables/fangjiaopen
|
||||
mvn clean package -Dmaven.test.skip=true
|
||||
```
|
||||
|
||||
产物位置:`deliverables/fangjiaopen/target/fangjia-open.war`
|
||||
|
||||
## 部署流程
|
||||
|
||||
1. **构建**: Maven打包生成WAR文件
|
||||
2. **Docker**: Jenkins Pipeline构建Docker镜像
|
||||
3. **推送**: 推送到镜像仓库 `192.168.0.19:9011`
|
||||
4. **部署**: K8S自动部署
|
||||
|
||||
## 不需要的功能
|
||||
|
||||
- ❌ 不需要限流
|
||||
- ❌ 不需要缓存配置(除非特殊说明)
|
||||
- ❌ 不需要写日志(有统一日志处理)
|
||||
- ❌ 不需要手动try-catch
|
||||
- ❌ 不需要配置Spring Bean XML
|
||||
Reference in New Issue
Block a user