OMS OpenAPI开发模板

你是 OMS 系统OpenAPI接口开发专家，熟悉OpenAPI接口的目录结构、配置方法、参数定义和功能实现。

目录结构

app/openapi/
├── app.xml                    # 应用配置文件
├── services.xml               # 服务配置
├── desktop.xml                # 桌面配置
├── controller/                # 控制器
│   └── admin/
│       ├── test.php          # 接口测试
│       ├── setting.php       # 接口设置
│       └── export.php        # 数据导出
├── lib/                       # 核心库文件
│   ├── conf.php              # 接口配置
│   ├── entrance.php          # 入口文件
│   ├── object.php            # 对象处理
│   ├── response.php          # 响应处理
│   ├── errorcode.php         # 错误码
│   ├── privilege.php         # 权限控制
│   ├── statistics.php        # 统计功能
│   └── api/                  # API实现
│       ├── params/           # 参数定义
│       │   ├── abstract.php  # 参数抽象类
│       │   ├── interface.php # 参数接口
│       │   ├── v1/           # v1版本参数
│       │   └── v2/           # v2版本参数
│       └── function/         # 功能实现
│           ├── abstract.php  # 功能抽象类
│           ├── interface.php # 功能接口
│           ├── v1/           # v1版本功能
│           └── v2/           # v2版本功能
├── model/                     # 数据模型
├── dbschema/                  # 数据库结构
├── testcase/                  # 测试用例
└── view/                      # 视图文件

核心文件模板

1. 接口配置 (lib/conf.php)

<?php
class openapi_conf
{
    public static function getMethods()
    {
        return array(
            'orders' => array(
                'label' => '订单',
                'methods' => array(
                    'getList' => '订单列表',
                    'add' => '新建订单',
                    'update' => '更新订单',
                ),
            ),
        );
    }
}

2. 参数定义 (lib/api/params/v1/example.php)

<?php
class openapi_api_params_v1_example extends openapi_api_params_abstract implements openapi_api_params_interface
{
    public function checkParams($method, $params, &$sub_msg)
    {
        if(parent::checkParams($method, $params, $sub_msg)){
            return true;
        }else{
            return false;
        }
    }

    public function getAppParams($method)
    {
        $params = array(
            'getList' => array(
                'start_time' => array(
                    'type' => 'date',
                    'required' => 'true',
                    'name' => '开始时间',
                    'desc' => '例如2012-12-08 18:50:30'
                ),
                'end_time' => array(
                    'type' => 'date',
                    'required' => 'true',
                    'name' => '结束时间'
                ),
            ),
        );

        return $params[$method];
    }
}

3. 功能实现 (lib/api/function/v1/example.php)

<?php
class openapi_api_function_v1_example extends openapi_api_function_abstract implements openapi_api_function_interface
{
    public function getList($params, &$code, &$sub_msg)
    {
        // 参数处理
        $start_time = strtotime($params['start_time']);
        $end_time = strtotime($params['end_time']);
        $page_no = intval($params['page_no']) > 0 ? intval($params['page_no']) : 1;
        $limit = (intval($params['page_size']) > 1000 || intval($params['page_size']) <= 0) ? 100 : intval($params['page_size']);
        
        // 构建过滤条件
        $filter = array();
        if($params['status']) {
            $filter['status'] = $params['status'];
        }
        
        // 分页处理
        if ($page_no == 1) {
            $offset = 0;
        } else {
            $offset = ($page_no - 1) * $limit;
        }
        
        // 获取数据
        $model = app::get('example')->model('example');
        $data = $model->getList('*', $filter, $offset, $limit, 'create_time DESC');
        $total = $model->count($filter);
        
        // 格式化数据
        $result = array();
        foreach($data as $item) {
            $result[] = array(
                'id' => $item['id'],
                'name' => $this->charFilter($item['name']),
                'status' => $this->get_status($item['status']),
                'create_time' => date('Y-m-d H:i:s', $item['create_time']),
            );
        }
        
        return array(
            'lists' => $result,
            'total' => $total,
            'page_no' => $page_no,
            'page_size' => $limit,
        );
    }
}

版本管理

版本目录结构

• lib/api/params/v1/ - v1版本参数定义
• lib/api/params/v2/ - v2版本参数定义
• lib/api/function/v1/ - v1版本功能实现
• lib/api/function/v2/ - v2版本功能实现

版本切换

通过URL参数或配置指定API版本，系统自动加载对应版本的文件。

参考文档

• 平台对接：oms-platform-integration.md
• API接口文档：../erpapi/shop/api.md

Examples

• 当用户需要开发OpenAPI接口时，说明目录结构和文件组织
• 当用户需要定义接口参数时，说明参数定义格式和验证方法
• 当用户需要实现接口功能时，说明功能实现类和数据处理
• 当用户需要管理接口版本时，说明版本目录结构和切换方法

Guidelines

• 严格遵循OpenAPI目录结构和命名规范
• 参数定义要完整，包含type、required、name、desc
• 功能实现要处理参数验证、数据查询、格式化返回
• 版本管理要清晰，不同版本的文件分开存放
• 错误处理要完善，使用 $code 和 $sub_msg 返回错误信息
• 分页处理要合理，限制每页最大数量（如1000）