LoveIt
所有文章 标签 分类 文档 关于
LoveIt

目录

多语言招聘网站API接口文档

geluli 收录于 接口文档
   约 2569 字   预计阅读 6 分钟 
目录

多语言招聘网站API接口文档

1. 接口设计概述

1.1 多语言支持机制

1.1.1 语言指定方式

方式 示例 优先级
URL参数 /api/jobs?lang=en 最高
HTTP头 Accept-Language: zh-CN 中等
用户偏好 登录用户设置的默认语言 低
系统默认 配置的默认语言 最低

1.1.2 多语言数据返回格式

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Software Engineer",
    "description": "We are looking for a talented software engineer...",
    // 其他字段
  },
  "i18n": {
    "messages": {
      "common.success": "操作成功",
      "job.apply.success": "申请提交成功"
    }
  }
}

1.2 认证与授权

1.2.1 JWT认证

  • 登录成功后返回JWT token
  • 所有需要认证的接口需在请求头中携带 ​Authorization: Bearer <token>
  • token有效期：24小时

1.2.2 角色权限

角色 权限范围
candidate 应聘者功能
company_admin 企业管理功能
super_admin 系统管理功能

2. 公共接口

2.1 获取支持的语言列表

GET /api/languages

响应示例

{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "en",
      "name": "English",
      "is_default": true
    },
    {
      "id": 2,
      "code": "zh-CN",
      "name": "简体中文",
      "is_default": false
    }
  ]
}

2.2 获取国家列表

GET /api/countries

响应示例

{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "CN",
      "name": "China",
      "currency": "CNY"
    },
    {
      "id": 2,
      "code": "US",
      "name": "United States",
      "currency": "USD"
    }
  ]
}

2.3 获取地区列表

GET /api/regions?country_id=1

响应示例

{
  "success": true,
  "data": [
    {
      "id": 1,
      "country_id": 1,
      "name": "Beijing"
    },
    {
      "id": 2,
      "country_id": 1,
      "name": "Shanghai"
    }
  ]
}

3. 用户认证接口

3.1 用户注册

POST /api/auth/register

请求体

{
  "email": "user@example.com",
  "password": "password123",
  "role": "candidate",
  "language_id": 1
}

响应示例

{
  "success": true,
  "data": {
    "id": 1,
    "email": "user@example.com",
    "role": "candidate",
    "language_id": 1
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

3.2 用户登录

POST /api/auth/login

请求体

{
  "email": "user@example.com",
  "password": "password123"
}

响应示例

{
  "success": true,
  "data": {
    "id": 1,
    "email": "user@example.com",
    "role": "candidate",
    "language_id": 1
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "i18n": {
    "messages": {
      "auth.login.success": "登录成功"
    }
  }
}

3.3 忘记密码

POST /api/auth/forgot-password

请求体

{
  "email": "user@example.com"
}

4. 应聘者接口

4.1 简历管理

4.1.1 获取简历列表

GET /api/candidates/resumes

响应示例

{
  "success": true,
  "data": [
    {
      "id": 1,
      "file_name": "resume.pdf",
      "file_type": "pdf",
      "size": 1024000,
      "is_default": true,
      "status": "approved"
    }
  ]
}

4.1.2 上传简历

POST /api/candidates/resumes/upload
Content-Type: multipart/form-data

请求体

  • file: 简历文件
  • is_default: 是否设为默认简历

4.1.3 设置默认简历

PUT /api/candidates/resumes/{id}/default

4.2 职位搜索

GET /api/jobs

查询参数

参数 类型 描述
keyword string 搜索关键词
job_type string 职位类型（full_time, part_time）
job_category string 职位类别（tech, marketing）
country_id integer 国家ID
region_id integer 地区ID
salary_min number 最低工资
salary_max number 最高工资
experience_min integer 最低经验（年）
page integer 页码
page_size integer 每页数量
lang string 语言代码

响应示例

{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": 1,
        "title": "Software Engineer",
        "company": {
          "id": 1,
          "name": "Tech Company",
          "logo": "https://example.com/logo.png"
        },
        "job_type": "full_time",
        "job_category": "tech",
        "location": "Beijing, China",
        "salary": "15K-25K CNY",
        "experience": "3-5 years"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 100,
      "total_pages": 10
    }
  }
}

4.3 职位详情

GET /api/jobs/{id}

响应示例

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Software Engineer",
    "description": "We are looking for a talented software engineer...",
    "requirements": "- Bachelor's degree in Computer Science\n- 3+ years of experience...",
    "responsibilities": "- Develop and maintain web applications\n- Collaborate with cross-functional teams...",
    "benefits": "- Competitive salary\n- Flexible working hours...",
    "company": {
      "id": 1,
      "name": "Tech Company",
      "description": "A leading tech company specializing in...",
      "website": "https://example.com",
      "logo": "https://example.com/logo.png"
    },
    "job_type": "full_time",
    "job_category": "tech",
    "country": "China",
    "region": "Beijing",
    "salary_min": 15000,
    "salary_max": 25000,
    "currency": "CNY",
    "experience_min": 3,
    "experience_max": 5,
    "education_level": "bachelor"
  }
}

4.4 投递申请

POST /api/jobs/{id}/apply

请求体

{
  "resume_id": 1,
  "cover_letter": "I am very interested in this position..."
}

4.5 我的申请

GET /api/candidates/applications

查询参数

  • status: 申请状态（pending, reviewed, accepted, rejected）
  • page: 页码
  • page_size: 每页数量

4.6 我的收藏

GET /api/candidates/favorites

4.6.1 添加收藏

POST /api/candidates/favorites

请求体

{
  "entity_type": "job",
  "entity_id": 1
}

4.6.2 取消收藏

DELETE /api/candidates/favorites/{id}

5. 企业接口

5.1 企业信息管理

5.1.1 获取企业信息

GET /api/companies/me

5.1.2 更新企业信息

PUT /api/companies/me

请求体

{
  "name": "Tech Company",
  "description": "A leading tech company...",
  "website": "https://example.com",
  "country_id": 1,
  "region_id": 1,
  "logo": "https://example.com/logo.png"
}

5.2 职位管理

5.2.1 发布职位

POST /api/companies/jobs

请求体

{
  "title": "Software Engineer",
  "description": "We are looking for a talented software engineer...",
  "requirements": "- Bachelor's degree in Computer Science...",
  "responsibilities": "- Develop and maintain web applications...",
  "benefits": "- Competitive salary...",
  "job_type_id": 1,
  "job_category_id": 1,
  "country_id": 1,
  "region_id": 1,
  "salary_min": 15000,
  "salary_max": 25000,
  "currency": "CNY",
  "experience_min": 3,
  "experience_max": 5,
  "education_level": "bachelor"
}

5.2.2 获取企业职位列表

GET /api/companies/jobs

查询参数

  • status: 职位状态（active, inactive）
  • page: 页码
  • page_size: 每页数量

5.2.3 更新职位

PUT /api/companies/jobs/{id}

5.2.4 下架职位

PUT /api/companies/jobs/{id}/deactivate

5.3 简历管理

5.3.1 获取收到的简历

GET /api/companies/applications

查询参数

  • job_id: 职位ID
  • status: 申请状态
  • page: 页码
  • page_size: 每页数量

5.3.2 查看简历详情

GET /api/companies/applications/{id}/resume

5.3.3 更新申请状态

PUT /api/companies/applications/{id}/status

请求体

{
  "status": "reviewed",
  "notes": "Good candidate, schedule an interview"
}

5.4 面试管理

5.4.1 发起面试

POST /api/companies/interviews

请求体

{
  "application_id": 1,
  "interview_date": "2024-01-15T14:00:00Z",
  "interview_type": "online",
  "location": "https://meeting.example.com/123",
  "notes": "Please prepare for technical interview"
}

5.4.2 获取面试列表

GET /api/companies/interviews

6. 多语言内容管理接口

6.1 动态内容翻译

6.1.1 获取实体翻译

GET /api/i18n/translations/{entity_type}/{entity_id}

6.1.2 添加/更新翻译

POST /api/i18n/translations

请求体

{
  "language_id": 2,
  "entity_type": "job",
  "entity_id": 1,
  "field_name": "title",
  "translation": "软件工程师"
}

6.2 静态内容翻译

6.2.1 获取静态内容翻译

GET /api/i18n/content/{content_key}

6.2.2 添加/更新静态内容翻译

POST /api/i18n/content

请求体

{
  "language_id": 2,
  "content_key": "home.title",
  "content_value": "欢迎来到招聘网站"
}

7. 管理员接口

7.1 语言管理

7.1.1 添加语言

POST /api/admin/languages

请求体

{
  "code": "fr",
  "name": "Français",
  "is_default": false
}

7.1.2 设置默认语言

PUT /api/admin/languages/{id}/default

7.2 国家/地区管理

7.2.1 添加国家

POST /api/admin/countries

请求体

{
  "code": "JP",
  "name": "Japan",
  "currency": "JPY"
}

7.2.2 添加地区

POST /api/admin/regions

请求体

{
  "country_id": 3,
  "name": "Tokyo"
}

7.3 用户管理

7.3.1 获取用户列表

GET /api/admin/users

查询参数

  • role: 用户角色
  • status: 用户状态
  • page: 页码
  • page_size: 每页数量

7.3.2 更新用户状态

PUT /api/admin/users/{id}/status

请求体

{
  "status": "active"
}

8. WebSocket实时通知接口

8.1 连接WebSocket

ws://example.com/ws?token={jwt_token}

8.2 通知类型

类型 描述
application_status_change 申请状态变更
interview_scheduled 面试安排
new_application 新的职位申请
message_received 收到新消息

8.3 通知数据格式

{
  "type": "application_status_change",
  "data": {
    "application_id": 1,
    "job_title": "Software Engineer",
    "status": "reviewed",
    "notes": "Good candidate"
  },
  "i18n": {
    "message": "您的申请状态已更新为：已查看"
  }
}

9. 错误码规范

错误码 描述 HTTP状态码
20000 操作成功 200
40000 请求参数错误 400
40100 未授权 401
40300 权限不足 403
40400 资源不存在 404
40900 资源冲突 409
50000 服务器内部错误 500
50001 数据库错误 500
50002 第三方服务错误 500

10. 示例请求响应

10.1 职位详情请求（中文）

GET /api/jobs/1?lang=zh-CN
Authorization: Bearer <token>

10.2 职位详情响应（中文）

{
  "success": true,
  "data": {
    "id": 1,
    "title": "软件工程师",
    "description": "我们正在寻找一位才华横溢的软件工程师...",
    "requirements": "- 计算机科学学士学位...",
    "responsibilities": "- 开发和维护Web应用...",
    "benefits": "- 有竞争力的薪资...",
    "company": {
      "id": 1,
      "name": "科技公司",
      "logo": "https://example.com/logo.png"
    },
    "job_type": "全职",
    "job_category": "技术",
    "location": "中国，北京",
    "salary": "15K-25K CNY",
    "experience": "3-5年"
  },
  "i18n": {
    "messages": {
      "job.detail.view": "查看职位详情",
      "job.apply": "立即申请",
      "job.favorite": "收藏职位"
    }
  }
}

11. API版本控制

  • API版本通过URL前缀控制，如 ​/api/v1/jobs
  • 支持多版本并存，便于平滑升级
  • 新版本API需保持向后兼容

12. 安全规范

  1. HTTPS：所有API请求必须使用HTTPS
  2. 输入验证：所有请求参数必须严格验证
  3. 输出过滤：所有响应数据必须过滤敏感信息
  4. 速率限制：防止API滥用，每个IP或用户设置请求频率限制
  5. SQL注入防护：使用参数化查询，防止SQL注入
  6. XSS防护：对输出内容进行HTML转义
  7. CSRF防护：对非GET请求进行CSRF验证

13. 性能优化

  1. 缓存策略：

    • 热门职位、公司信息缓存
    • 翻译内容缓存
    • 静态内容缓存

  2. 分页处理：所有列表接口必须支持分页

  3. 异步处理：

    • 邮件发送异步处理
    • 通知推送异步处理
    • 简历解析异步处理

  4. 数据库优化：

    • 合理设计索引
    • 避免N+1查询
    • 大表分区

14. 部署建议

  1. API网关：使用API网关统一管理API请求，包括认证、限流、监控等

  2. 负载均衡：多实例部署，使用负载均衡分发请求

  3. 容器化部署：使用Docker容器化部署，便于扩展和管理

  4. CI/CD：实现自动化构建、测试和部署

  5. 监控与日志：

    • 接入APM监控系统
    • 完善的日志记录
    • 实时告警机制

15. 文档更新日志

日期 版本 更新内容
2024-01-01 v1.0 初始版本
2024-01-15 v1.1 添加WebSocket通知接口
2024-02-01 v1.2 完善多语言支持机制

API文档版本：v1.2
最后更新：2024-02-01
适用系统：多语言招聘网站

更新于 2026-09-24
阅读原始文档
返回 | 主页