新闻系统 API 文档
新闻分类、新闻列表和新闻详情接口文档
📰 新闻分类接口
📋 接口基本信息
GET
https://hapi.caixiangxiang.com/News/GetNewsTypes
功能描述：获取系统所有可用的新闻分类列表，用于前端导航和筛选。
📤 请求参数
此接口无需任何请求参数。
📥 响应数据
成功响应
错误响应
HTTP状态码：200
{
"statusCode": 200,
"message": "获取成功",
"data": [
{
"id": 1,
"name": "通知公告",
"news_count": 15,
"status": 1
},
{
"id": 2,
"name": "城市动态",
"news_count": 8,
"status": 1
},
{
"id": 3,
"name": "新闻观点",
"news_count": 12,
"status": 1
}
]
}
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| statusCode | Integer | 状态码，200表示成功 |
| message | String | 操作结果消息 |
| data | Array[Object] | 分类对象列表 |
| data[].id | Integer | 分类的唯一标识ID |
| data[].name | String | 分类名称 |
| data[].news_count | Integer | 该分类下的新闻数量 |
| data[].status | Integer | 分类状态：1-启用，0-禁用 |
| HTTP状态码 | 错误消息 | 可能原因 |
|---|---|---|
| 500 | 获取分类列表失败 | 服务器内部错误 |
🔍 使用示例
JavaScript Fetch 示例
// 获取新闻分类列表
fetch('https://hapi.caixiangxiang.com/News/GetNewsTypes')
.then(response => response.json())
.then(data => {
if (data.statusCode === 200) {
console.log('新闻分类数据:', data.data);
// 处理分类数据
}
})
.catch(error => {
console.error('获取分类失败:', error);
});
cURL 示例
curl -X GET "https://hapi.caixiangxiang.com/News/GetNewsTypes"
📄 新闻列表接口
📋 接口基本信息
GET
https://hapi.caixiangxiang.com/News/GetNewsList
功能描述：获取新闻列表，支持分页、分类筛选和地域定向功能。
📤 请求参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| type_id | Integer | 否 | 0 | 新闻类型ID，0表示获取所有分类 |
| page | Integer | 否 | 1 | 页码，从1开始计数 |
| pageSize | Integer | 否 | 10 | 每页显示数量，最大值100 |
| keyword | String | 否 | 空 | 搜索关键词，在标题和描述中搜索 |
| is_stick | Integer | 否 | null | 是否置顶：1-置顶，0-非置顶，null-全部 |
📥 响应数据
成功响应
错误响应
HTTP状态码：200
{
"statusCode": 200,
"message": "获取成功",
"data": {
"list": [
{
"id": 1,
"title": "重要通知：系统维护公告",
"type_id": 1,
"type_name": "通知公告",
"thumbnail": "https://example.com/images/news1.jpg",
"desc": "系统将于本周六进行维护升级",
"click": 150,
"is_stick": 1,
"stick_weight": 100,
"create_time": "2025-12-01 10:30:00",
"has_video": false,
"has_thumbnail": true
},
{
"id": 2,
"title": "城市马拉松赛事即将开幕",
"type_id": 2,
"type_name": "城市动态",
"thumbnail": "https://example.com/images/news2.jpg",
"desc": "年度城市马拉松赛事即将在本周末举行",
"click": 89,
"is_stick": 0,
"stick_weight": 0,
"create_time": "2025-12-02 14:20:00",
"has_video": true,
"has_thumbnail": true
}
],
"pagination": {
"totalCount": 45,
"pageSize": 10,
"currentPage": 1,
"pageCount": 5
}
}
}
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| statusCode | Integer | 状态码，200表示成功 |
| message | String | 操作结果消息 |
| data | Object | 数据对象 |
| data.list | Array[Object] | 新闻对象列表 |
| data.list[].id | Integer | 新闻的唯一标识 |
| data.list[].title | String | 新闻标题 |
| data.list[].type_id | Integer | 新闻类型ID |
| data.list[].type_name | String | 新闻类型名称 |
| data.list[].thumbnail | String | 新闻缩略图URL |
| data.list[].desc | String | 新闻描述 |
| data.list[].click | Integer | 点击量 |
| data.list[].is_stick | Integer | 是否置顶：1-是，0-否 |
| data.list[].stick_weight | Integer | 置顶权重，值越大排序越靠前 |
| data.list[].create_time | String | 创建时间 |
| data.list[].has_video | Boolean | 是否有视频 |
| data.list[].has_thumbnail | Boolean | 是否有缩略图 |
| data.pagination | Object | 分页信息对象 |
| data.pagination.totalCount | Integer | 总记录数 |
| data.pagination.pageSize | Integer | 每页数量 |
| data.pagination.currentPage | Integer | 当前页码 |
| data.pagination.pageCount | Integer | 总页数 |
| HTTP状态码 | 错误消息 | 可能原因 |
|---|---|---|
| 400 | 参数错误 | 参数格式不正确 |
| 500 | 获取新闻列表失败 | 服务器内部错误 |
🔍 使用示例
获取第一页新闻（默认参数）
// 获取新闻列表
fetch('https://hapi.caixiangxiang.com/News/GetNewsList?page=1&pageSize=10')
.then(response => response.json())
.then(data => {
if (data.statusCode === 200) {
console.log('新闻数据:', data.data.list);
console.log('分页信息:', data.data.pagination);
}
});
获取指定分类的置顶新闻
// 获取通知公告分类的置顶新闻
fetch('https://hapi.caixiangxiang.com/News/GetNewsList?type_id=1&is_stick=1&pageSize=5')
.then(response => response.json())
.then(data => {
// 处理返回的新闻数据
});
搜索新闻
// 搜索包含"赛事"关键词的新闻
fetch('https://hapi.caixiangxiang.com/News/GetNewsList?keyword=赛事&page=1&pageSize=20')
.then(response => response.json())
.then(data => {
// 处理搜索结果
});
📰 新闻详情接口
📋 接口基本信息
GET
https://hapi.caixiangxiang.com/News/GetNewsDetail
功能描述：获取指定新闻的详细信息，包括完整内容和相关元数据。
📤 请求参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| id | Integer | 是 | 无 | 新闻的唯一标识ID |
📥 响应数据
成功响应
错误响应
HTTP状态码：200
{
"statusCode": 200,
"message": "获取成功",
"data": {
"id": 1,
"title": "重要通知：系统维护公告",
"type_id": 1,
"type_name": "通知公告",
"video_url": "https://example.com/videos/news1.mp4",
"thumbnail": "https://example.com/images/news1.jpg",
"desc": "系统将于本周六进行维护升级",
"content": "尊敬的用户：
系统将于本周六（12月5日）凌晨2:00-6:00进行维护升级...", "link": null, "province": 110000, "city": 110100, "district": 110101, "click": 152, "status": 1, "create_at": "2025-12-01 10:30:00", "banner_title": "系统维护公告", "banner_img": "https://example.com/banners/news1.jpg", "banner_desc": "本周六系统维护通知", "is_stick": 1, "stick_weight": 100, "admin_id": 1, "has_video": true, "has_banner": true, "create_time": "2025-12-01 10:30:00" } }
系统将于本周六（12月5日）凌晨2:00-6:00进行维护升级...", "link": null, "province": 110000, "city": 110100, "district": 110101, "click": 152, "status": 1, "create_at": "2025-12-01 10:30:00", "banner_title": "系统维护公告", "banner_img": "https://example.com/banners/news1.jpg", "banner_desc": "本周六系统维护通知", "is_stick": 1, "stick_weight": 100, "admin_id": 1, "has_video": true, "has_banner": true, "create_time": "2025-12-01 10:30:00" } }
响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| statusCode | Integer | 状态码，200表示成功 |
| message | String | 操作结果消息 |
| data | Object | 新闻详情对象 |
| data.id | Integer | 新闻的唯一标识 |
| data.title | String | 新闻标题 |
| data.type_id | Integer | 新闻类型ID |
| data.type_name | String | 新闻类型名称 |
| data.video_url | String | 视频URL（如果有视频） |
| data.thumbnail | String | 新闻缩略图URL |
| data.desc | String | 新闻描述 |
| data.content | String | 新闻完整内容（HTML格式） |
| data.link | String | 外部链接（如果有） |
| data.click | Integer | 点击量 |
| data.status | Integer | 新闻状态：1-启用，0-禁用 |
| data.create_time | String | 创建时间 |
| data.banner_title | String | Banner标题 |
| data.banner_img | String | Banner图片URL |
| data.is_stick | Integer | 是否置顶：1-是，0-否 |
| data.stick_weight | Integer | 置顶权重，值越大排序越靠前 |
| data.has_video | Boolean | 是否有视频 |
| data.has_banner | Boolean | 是否有Banner |
| HTTP状态码 | 错误消息 | 可能原因 |
|---|---|---|
| 400 | 参数错误 | 新闻ID格式不正确 |
| 404 | 新闻不存在 | 指定的新闻ID不存在 |
| 500 | 获取新闻详情失败 | 服务器内部错误 |
🔍 使用示例
JavaScript Fetch 示例
// 获取新闻详情
fetch('https://hapi.caixiangxiang.com/News/GetNewsDetail?id=1')
.then(response => response.json())
.then(data => {
if (data.statusCode === 200) {
console.log('新闻详情:', data.data);
// 处理新闻详情数据
}
})
.catch(error => {
console.error('获取新闻详情失败:', error);
});
cURL 示例
curl -X GET "https://hapi.caixiangxiang.com/News/GetNewsDetail?id=1"
处理富文本内容示例
// 获取新闻详情并处理富文本内容
fetch('https://hapi.caixiangxiang.com/News/GetNewsDetail?id=1')
.then(response => response.json())
.then(data => {
if (data.statusCode === 200) {
const news = data.data;
// 处理富文本内容中的图片显示问题
if (news.content) {
// 为图片添加最大宽度限制
news.content = news.content.replace(
/![]()
💡 最佳实践
1. 错误处理
建议在调用API时添加完善的错误处理机制：
async function getNewsDetail(id) {
try {
const response = await fetch(`https://hapi.caixiangxiang.com/News/GetNewsDetail?id=${id}`);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const result = await response.json();
if (result.statusCode === 200) {
return result.data;
} else {
console.error('API返回错误:', result.message);
// 根据不同的错误码进行相应处理
switch(result.statusCode) {
case 404:
// 处理新闻不存在的情况
break;
case 500:
// 处理服务器错误
break;
default:
// 处理其他错误
}
return null;
}
} catch (error) {
console.error('获取新闻详情失败:', error);
return null;
}
}
2. 缓存策略
根据新闻的更新频率设置合适的缓存策略：
- 实时新闻：缓存时间较短（2-5分钟）
- 普通新闻：缓存时间适中（10-30分钟）
- 静态新闻：缓存时间较长（1-2小时）
3. 性能优化
对于新闻详情页，可以采用以下优化策略：
// 图片懒加载
function lazyLoadImages() {
const images = document.querySelectorAll('img[data-src]');
const imageObserver = new IntersectionObserver((entries, observer) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
const img = entry.target;
img.src = img.dataset.src;
img.removeAttribute('data-src');
imageObserver.unobserve(img);
}
});
});
images.forEach(img => imageObserver.observe(img));
}
// 在新闻内容加载完成后调用
lazyLoadImages();