- AverageStatistics 新增 xingfuliEsfPrice、maitianEsfPrice 字段 - AverageStatisticsService 新增 findRecentMonths 方法(查询最近N个月数据) - PropertyController 新增 thirdPartyPriceAction(/property/thirdPartyPrice) - 返回幸福里、安居客、房天下、链家、城市房产、吉屋、淘房365、麦田均价 - 仅取二手房价格,最多回溯3个月补全空值 - 新增 opentest 测试脚本:数据提取 + 多线程接口测试 - 更新 claude 技能文档:修正本地端口、seaweed集合字段说明、Groovy static 限制 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
17 KiB
name, description
| name | description |
|---|---|
| fangjia-openapi-dev | 房价开放平台(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文档:
# 使用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/{业务模块}/
必须创建:
- Service接口 - 参考 code-templates.md "Service 接口模板"
- Service实现类 - 参考 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 "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 生成文档内容
按照模板格式生成:
- 接口地址:根据Controller和方法名确定URL
- 输入参数表格:
- 参数名
- 参数类型(String/Integer/Float等)
- 是否必填
- 说明
- 响应参数表格:
- 名称
- 类型
- 描述
- 响应示例:生成JSON格式示例
3.3 文档生成方式
方式1:使用docx-js生成(强烈推荐)
重要:为确保表格样式与模板完全一致,强烈推荐使用docx-js库直接生成Word文档。
使用pandoc转换可能导致:
- ❌ 表格边框样式不一致
- ❌ 表头背景色不匹配
- ❌ 单元格内边距不同
参考代码示例:
// 创建表格时指定边框样式
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:
pandoc api-doc.md -o api-doc.docx --reference-doc=".claude/skills/fangjia-openapi-dev/assets/估家科技开放接口文档-模版.docx"
开发规范
关键规范速查
| 项目 | 规范 |
|---|---|
| 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等)
使用示例
// 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 字段来确定匹配是否成功。
// 调用地址匹配服务
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 字段。
// 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. 数据来源分离原则 ⭐⭐⭐
核心原则:展示字段和查询字段使用不同的数据源。
// 从匹配结果获取展示用的数据(用户友好格式)
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. 区域价格查询前必须格式化 ⭐⭐⭐
问题:区域价格查询必须使用城市和区域的简称,否则查不到数据。
// 错误示例 ❌
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 可能导致异常。
// 错误示例 ❌
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 字段。
// 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 字段判断匹配结果的类型。
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 注解。
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 封装结果:
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 "参数校验" 章节
Q3: 需要配置Spring Bean吗?
不需要。约定大于配置,只要提供setter方法即可自动注入。
Q4: 本地如何测试?
cd deliverables/fangjiaopen
mvn tomcat7:run
# 访问: http://localhost:9180/{controller}/{action}?param=value&token=xxx
Q5: 如何构建部署?
cd deliverables/fangjiaopen
mvn clean package -Dmaven.test.skip=true
# WAR包位置: target/fangjia-open.war
# 后续通过Jenkins Pipeline自动部署到K8S
工作流程总结
- 读取需求 → 使用pandoc转换Word/PDF
- 分析需求 → 提取参数、字段、逻辑
- 询问确认 → URL、数据源、Service/DAO
- 给出建议 → 命名、字段、异常处理
- 生成代码 → DAO(如需要) → Service → Controller
- 返回数据使用UniversalDto,字段名用下划线分隔
- 优先复用现有Service(AddressMatchProxyService、DistrictStatService等)
- 生成文档 → 使用docx-js生成Word格式API文档(确保样式一致)
- 接口测试 → 参考 API测试指南
参考资料
- 代码模板 - Controller、Service代码模板
- 开发规范 - 完整的开发规范文档
- API测试指南 - 接口测试流程和脚本编写
- 数据表参考 - 常用MongoDB数据表结构和查询方法
- API文档模板:
assets\估家科技开放接口文档-模版.docx
常用工具类
详见项目根目录下的 CLAUDE.md 文件中的"常用工具类"章节。